Skip to content

workspace-agent-runner

Status: Preview | Last reviewed: 2026-09-11

The internal generation-status response includes credential-free metrics and settled fields for the authoring benchmark. Metrics are held in runner memory; the local controller snapshots them before expiry. Explicit per-job experiments can use a metered Responses loop while the product's OpenAI default remains the managed Agents API.

Sandboxed Assistant Agent runtime for OpenAI Codex CLI and Anthropic Claude Code chat stages.

Also hosts Generate with AI and persistent editor/designer sessions. These authoring endpoints support Claude Code and OpenAI Agents API. OpenAI runs through a function bridge with no sandbox, shell or model-accessible credentials. It uses the same target-scoped MCP tools, concurrency limits and wall clocks. Runtime chat stages retain their CLI implementation.

Source

apps/workspace-agent-runner

Runtime

Aspect Value
Language Python 3.13
Framework FastAPI
Port 8012
Sandbox Dedicated process/container, ephemeral workspace, no ambient TrueServe secrets, outer resource/network policy expected in deployment

What it does

  1. Receives an internal streaming turn request from ai-orchestrator.
  2. Creates a fresh per-turn workspace under WORKSPACE_AGENT_RUNNER_WORKSPACE_DIR.
  3. Writes AGENTS.md, CLAUDE.md, .trueserve/environment.json, and .trueserve/tools.json.
  4. Prepares CLI-local home and cache directories such as .codex/, .config/, .cache/, and .local/share/ inside the ephemeral workspace so the CLIs never need host user state.
  5. Materializes selected Library Skills and Inline Skills under .agents/skills/<skill>/.
  6. Runs the selected CLI:
  7. codex exec --json for OpenAI Codex.
  8. claude -p --output-format stream-json --verbose for Claude Code.
  9. Applies provider-specific auth metadata for Claude Code:
  10. Native Anthropic: ANTHROPIC_API_KEY and optional ANTHROPIC_BASE_URL.
  11. AWS Bedrock: CLAUDE_CODE_USE_BEDROCK=1, AWS_REGION, optional standard AWS credentials, or AWS_BEARER_TOKEN_BEDROCK.
  12. Google Vertex AI: CLAUDE_CODE_USE_VERTEX=1, CLOUD_ML_REGION, ANTHROPIC_VERTEX_PROJECT_ID, and workspace-local GOOGLE_APPLICATION_CREDENTIALS when a Google service-account JSON is supplied.
  13. Normalizes CLI JSONL into TrueServe text, thought, tool_call, tool_result, artifact_summary, and error events.
  14. Redacts temporary workspace paths before events reach a user-facing surface.
  15. Deletes the ephemeral workspace when the stream closes.

Current preview boundaries

  • This runner is for the new Assistant Agent service type, not ordinary LLM stages.
  • The turn prompt is built from the stage's system_instruction plus the latest user text. ai-orchestrator promotes the agent editor's Behavior-tab Prompt (config.template.inline) into system_instruction at build time; the messages array is not consumed by the runner. The legacy per-stage system_instruction/messages/runner_url/raw-skills fields were migrated away and removed (see universal-pipeline-builder); sandbox is still an enforced policy, just hidden from the editor.
  • Codex and Claude run as local CLI subprocesses inside the runner. They are not executed inside ai-orchestrator.
  • Skills are shared with Antigravity: selected library and inline skills compile into SKILL.md packages.
  • Governed TrueServe MCP/API/Python/workflow/A2UI tools are still resolved by ai-orchestrator. Native CLI-side MCP execution should wait for a session-scoped TrueServe MCP gateway.
  • Shell command approval is not interactive in v1. The default Codex/Claude Assistant Agent sandbox policy sets command_policy="deny"; enabling shell commands requires an explicit runtime policy and an outer sandbox.
  • Missing codex or claude binaries stream an error event instead of falling back to fake output.

Environment variables

Name Default Purpose
WORKSPACE_AGENT_RUNNER_PORT 8012 HTTP port
WORKSPACE_AGENT_RUNNER_FAKE false Deterministic fake stream mode for local tests
WORKSPACE_AGENT_RUNNER_USE_DOCKER true Local launcher mode; runs the Docker image with Python 3.13 and bundled CLIs
WORKSPACE_AGENT_RUNNER_WORKSPACE_DIR /workspace-tmp/workspace-agent Parent directory for ephemeral workspaces
WORKSPACE_AGENT_RUNNER_CODEX_BIN codex Codex CLI binary name/path
WORKSPACE_AGENT_RUNNER_CLAUDE_BIN claude Claude Code CLI binary name/path
CODEX_API_KEY / OPENAI_API_KEY — Codex CLI credentials when not supplied by the stage config
ANTHROPIC_API_KEY — Native Anthropic Claude Code credentials when not supplied by the stage config
AWS_BEARER_TOKEN_BEDROCK — Bedrock API-key fallback for Claude Code when no AWS integration supplies one
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN / AWS_REGION — AWS credential-chain fallback for Claude Code on Bedrock
GOOGLE_APPLICATION_CREDENTIALS / ANTHROPIC_VERTEX_PROJECT_ID / CLOUD_ML_REGION — Google Vertex fallback for Claude Code when no Google integration supplies them

Vanguard

Started by start-workspace-agent-runner.sh under Overmind.

overmind restart workspace-agent-runner
overmind connect workspace-agent-runner

Set WORKSPACE_AGENT_RUNNER_FAKE=true for stream and UI tests without invoking the CLIs. The normal local path uses WORKSPACE_AGENT_RUNNER_USE_DOCKER=true to build and run the Docker image, which provides Python 3.13 plus @openai/codex and @anthropic-ai/claude-code.

Production

Helm chart at charts/workspace-agent-runner. Keep readOnlyRootFilesystem=true, mount the workspace on tmpfs, run as non-root, enable gVisor where available, and keep egress default-deny except for the approved proxy. The umbrella chart wires ai-orchestrator to http://workspace-agent-runner:8012 through WORKSPACE_AGENT_RUNNER_URL.

See also