Runner Service Infrastructure#

The runner (formerly sandbox-agent) is a Node.js/TypeScript sidecar service that executes agent workloads inside isolated sandboxes. It lives at services/runner/ (renamed from services/agent/ in PR #4968) and exposes an HTTP API on port 8765. The Python services container calls the runner over the Docker network for all sandboxed execution.

The service was first wired into the dev compose stack in PR #4776 and had its CI pipeline and GHCR publication established in PR #4804.

Architecture#

The runner is a sidecar to the services container. services routes all agent execution requests to http://runner:8765 (configured via AGENTA_RUNNER_INTERNAL_URL) and depends on the runner being healthy before it starts 1.

┌────────────────────────┐ http://runner:8765
│ services (Python API) │ ──────────────────────────► runner (Node.js / TS)
└────────────────────────┘ │
                                                        ├── local sandbox provider
                                                        └── daytona cloud sandbox

Key design choices:

• Intentionally isolated env: The runner receives no env_file from the main stack. It only gets its own port, auth token, Pi credentials, and Daytona API keys — never application-layer secrets 1.
• Elevated Linux capabilities: Durable session workspaces use geesefs (FUSE) for S3-backed mounts. The runner container therefore requires SYS_ADMIN capability, /dev/fuse device access, and apparmor:unconfined 1.
• Token auth: AGENTA_RUNNER_TOKEN must be set and shared between services and runner. The runner defaults to loopback (127.0.0.1) but binds to 0.0.0.0 in compose so the sidecar is reachable cross-container 1.
• Sandbox providers: AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS and AGENTA_RUNNER_DEFAULT_SANDBOX_PROVIDER control which execution backends are active (default: local in dev) 1.

Docker Compose Configuration#

Dev (EE) — hosting/docker-compose/ee/docker-compose.dev.yml#

The runner service 1:

• Image: agenta-ee-dev-runner:latest, built from services/runner using docker/Dockerfile.dev
• Command: rebuilds the Pi extension (node scripts/build-extension.mjs), then launches tsx src/server.ts
• Volumes:
  • services/runner/src:/app/src — live-reload source
  • services/runner/skills:/app/skills — agent harness skills
  • ~/.pi/agent:/pi-agent:rw — read-write Pi OAuth token (persists refreshes back to host)
• Health check: polls http://127.0.0.1:8765/health via Node fetch, 20 s start period, 10 s interval, 12 retries
• Runtime: cap_add: [SYS_ADMIN], device /dev/fuse, apparmor:unconfined

The services container passes AGENTA_RUNNER_INTERNAL_URL=http://runner:8765 and depends on runner: condition: service_healthy 1.

Production / GH (OSS) — hosting/docker-compose/oss/docker-compose.gh.yml#

The snapshot of the OSS GH compose in this knowledge base predates the runner's addition 2. PR #4804 added AGENTA_SANDBOX_AGENT_IMAGE_NAME / AGENTA_SANDBOX_AGENT_IMAGE_TAG env-file hooks for configuring the runner image in production 3. PR #4968 subsequently wired the runner sidecar into all deployment surfaces — EE, OSS gh/gh.ssl, Helm, and Railway — completing non-dev coverage 4.

GHCR Publication & CI#

PR #4804 added two GitHub Actions jobs for the runner 3:

Build & publish (.github/workflows/42-railway-build.yml):

• Builds a multi-arch image (amd64 + arm64) from services/runner
• Dockerfile: services/runner/docker/Dockerfile
• Published to ghcr.io/agenta-ai/agenta-sandbox-agent (now renamed to agenta-runner following PR #4968) 4

Unit tests (.github/workflows/12-check-unit-tests.yml):

• Job: run-services-node-unit-tests
• Runs pnpm run typecheck (TypeScript) and pnpm run test:unit (vitest)
• Publishes JUnit results from services/runner/test-results/junit.xml

Note on distributed images: Published images do not bundle Claude Code. Claude is installed at runtime from Anthropic. Self-hosted operators who want Daytona sandboxes pre-loaded with the Pi CLI can build a custom snapshot using services/runner/sandbox-images/daytona/build_snapshot.py — this must be run in their own Daytona account 3.

Key Environment Variables#

1 Variables were previously prefixed AGENTA_AGENT_RUNNER_*; renamed to AGENTA_RUNNER_* in PR #4968.

Primary Sources#