Agent Runtimes

Parallax can spawn and manage CLI-based AI agents dynamically, enabling on-demand agent orchestration across multiple runtime environments.

Managed threads build on top of these runtimes, giving the control plane a durable orchestration unit for long-lived coding work.

What are Agent Runtimes?

Agent Runtimes allow Parallax to:

• Spawn CLI agents (Claude Code, Codex, Gemini CLI) on demand
• Manage agent lifecycle (start, communicate, monitor, stop)
• Scale across local, Docker, and Kubernetes environments
• Project runtime signals into thread events for orchestration and memory

Supported Agent Types

Agent Type	CLI Tool	Description
claude	Claude Code	Anthropic's Claude CLI for coding tasks
codex	Codex CLI	OpenAI's Codex CLI
gemini	Gemini CLI	Google's Gemini CLI

Runtime Environments

Runtime	Use Case	Requirements
Local	Development	Node.js, CLI tools installed
Docker	Staging/Testing	Docker daemon
Kubernetes	Production	K8s cluster with CRD support

Quick Start

1. Start a Runtime Server

# Local development
cd packages/runtime-local
pnpm build && pnpm start
# Server starts on port 3100

2. Configure Control Plane

export PARALLAX_LOCAL_RUNTIME_URL=http://localhost:3100
cd packages/control-plane
pnpm start

3. Spawn an Agent

curl -X POST http://localhost:3000/api/managed-agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "type": "claude",
    "capabilities": ["code_review"]
  }'

4. Send a Task

curl -X POST http://localhost:3000/api/managed-agents/agent-123/send \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Review auth.ts for security issues",
    "expectResponse": true
  }'

API Reference

Core Endpoints

Method	Endpoint	Description
POST	/api/managed-agents	Spawn new agent
POST	/api/managed-threads	Spawn new managed thread
POST	/api/managed-threads/prepare	Build thread preparation without spawning
GET	/api/managed-agents	List all agents
GET	/api/managed-threads	List all threads
GET	/api/managed-agents/:id	Get agent details
GET	/api/managed-threads/:id	Get thread details
POST	/api/managed-agents/:id/send	Send message to agent
POST	/api/managed-threads/:id/send	Send input to thread
GET	/api/managed-agents/:id/logs	Get agent logs
GET	/api/managed-agents/:id/metrics	Get agent metrics
DELETE	/api/managed-agents/:id	Stop agent
DELETE	/api/managed-threads/:id	Stop thread

Spawn Request

{
  name: string;           // Agent name
  type: 'claude' | 'codex' | 'gemini';
  capabilities?: string[];
  workdir?: string;       // Working directory
  env?: Record<string, string>;
  runtime?: 'local' | 'docker' | 'kubernetes';
}

Agent Response

{
  id: string;
  name: string;
  type: string;
  status: 'starting' | 'ready' | 'busy' | 'error' | 'stopped';
  runtime: string;
  createdAt: string;
}

WebSocket Endpoints

The runtime provides real-time WebSocket endpoints for UI integration:

Terminal Streaming

Connect directly to an agent's PTY for xterm.js integration:

ws://localhost:3100/ws/agents/:id/terminal

const ws = new WebSocket(`ws://runtime:3100/ws/agents/${agentId}/terminal`);

// Raw terminal output -> xterm.js
ws.onmessage = (e) => terminal.write(e.data);

// Keyboard input -> PTY
terminal.onData((data) => ws.send(data));

// Resize
ws.send(JSON.stringify({ type: 'resize', cols: 120, rows: 40 }));

Event Streaming

Subscribe to agent lifecycle events:

ws://localhost:3100/ws/events
ws://localhost:3100/ws/events?agentId=abc-123  # Filter by agent

Event	Data	Description
agent_started	{ agent }	Agent spawned
agent_ready	{ agent }	Agent ready for commands
agent_stopped	{ agent, reason }	Agent stopped
agent_error	{ agent, error }	Error occurred
login_required	{ agent, loginUrl }	Authentication needed
message	{ message }	Agent output
question	{ agent, question }	Agent needs input
thread_event	{ thread, event }	Normalized managed-thread event

const ws = new WebSocket('ws://runtime:3100/ws/events');

ws.onmessage = (e) => {
  const { event, data } = JSON.parse(e.data);
  if (event === 'login_required') {
    // Show terminal UI for authentication
    openTerminal(data.agent.id);
  }
};

Multi-Runtime Selection

When multiple runtimes are configured, selection uses priority:

1. Explicit - If specified in spawn request
2. Local (priority 10) - Best for development
3. Docker (priority 20) - Good for staging
4. Kubernetes (priority 30) - Best for production

Integration with Patterns

Managed agents work with org-chart patterns:

structure:
  roles:
    architect:
      agentType: claude
      managed: true  # Spawn via runtime
      capabilities:
        - architecture

Patterns and org charts can now also supervise thread-backed roles and thread-backed worker pools. See Threads and Managed Threads API.

Next Steps

• Local Runtime - Development setup
• Docker Runtime - Container-based agents
• Kubernetes Runtime - Production deployment
• Org-Chart Patterns - Hierarchical orchestration
• Threads - Long-lived orchestration units