Skip to main content

Deploy the Agent Runner

Agenta agent workflows run through a separate runner service. The Services API sends agent runs to this service through AGENTA_RUNNER_URL.

The runner owns the harness process lifecycle and runner-scoped sandbox provider settings. It should not inherit the full stack environment file.

Docker Compose​

The bundled Compose files include runner by default. The Services API points to it inside the Compose network:

AGENTA_RUNNER_URL=http://runner:8765

Use these variables when you need to override the image or default sandbox provider:

AGENTA_RUNNER_IMAGE_NAME=agenta-runner
AGENTA_RUNNER_IMAGE_TAG=latest
SANDBOX_AGENT_PROVIDER=local

Helm​

The Helm chart enables the runner by default:

agentRunner:
  enabled: true
  port: 8765
  provider: local

When agentRunner.enabled=true, the chart creates a runner Deployment and Service and injects the in-cluster URL into the Services pod as AGENTA_RUNNER_URL.

To use an external runner instead:

agentRunner:
  enabled: false
  externalUrl: https://runner.example.com

Railway​

The Railway scripts create a runner service and configure the Services API with the runner's private Railway URL. For image-based deploys, provide the runner image with the other Agenta images:

export AGENTA_RUNNER_IMAGE="ghcr.io/agenta-ai/agenta-runner:latest"