Skip to main content
Version: v2.0

How agents run

This page explains where agent code runs in a self-hosted Agenta deployment, and the pieces that decide how a single run behaves. It is the model behind the configuration pages that follow.

The runner service​

Services does not run agent code. It sends each agent run to one runner service over an internal URL and a shared token:

Services  --(AGENTA_RUNNER_INTERNAL_URL, AGENTA_RUNNER_TOKEN)-->  Runner

The runner owns sandbox execution. It receives a run request, starts a harness process inside a sandbox, streams results back, and relays server-side tools. A deployment has one logical runner. Its replicas all share the same provider configuration.

Harness and sandbox​

Two separate choices shape a run:

  • The harness is the agent program that runs: Pi, or Claude Code.
  • The sandbox provider is where that program runs: the local runner container, or a Daytona cloud sandbox.

The two are independent. One runner can serve local runs and Daytona runs at the same time, and changing one does not change the other.

The sandbox providers are:

A deployment enables the providers it wants and picks a default with AGENTA_RUNNER_ENABLED_SANDBOX_PROVIDERS.

Credentials​

Two kinds of credential meet at the runner:

  • Model keys are per-run data. Agenta resolves the model key for each run and passes it with the run request. It is not part of the runner's configuration.
  • Provider credentials are deployment infrastructure. The runner's Daytona API key belongs to the deployment. It is configured once on the runner and never travels to a sandbox.

A run can also carry no managed key at all and authenticate the harness from a mounted personal subscription. See Use your own subscription.

What the sandbox can see​

A model key would normally arrive in the sandbox as an environment variable, and an MCP server's key as a request header. Both would be readable by the agent running there, which matters because an agent writes and runs its own code: a prompt injection that convinces it to print its environment would print your keys.

On Daytona the runner closes that gap, and it does so by default. It stores each key as a Daytona Secret restricted to the single hostname that key authenticates against, then puts a placeholder in the sandbox. Daytona swaps the placeholder for the real value on requests to that host, so the model call and the MCP call still work while the agent itself only ever holds a useless string. A request to any other host carries the placeholder, which is what makes exfiltration fail.

This needs a Daytona API key that is allowed to manage Secrets, which is a different permission from creating sandboxes. See Hiding API keys from the sandbox for the upgrade note and for how to switch it off if you would rather not grant that permission.

This works for a key the remote service reads over HTTPS, which covers the provider keys and the MCP keys. It does not work for a key a provider SDK signs with locally, which today means the AWS access keys behind Bedrock: that secret never leaves the sandbox, so there is no outbound request to substitute it into, and the sandbox holds the real value.

The local sandbox is unaffected. The harness runs inside the runner container there, so its keys are already inside your own deployment rather than a third party's.

Persistence depends on the run​

What a run keeps depends on what the run is:

The run hasWhat it keeps
No session and no workflow artifactNothing. Its working directory is ephemeral.
A sessionA session working directory, restored on the next turn.
A workflow artifactAn agent working directory tied to that artifact.
A resumable harness sessionThe harness transcript, so the session continues.

Durable working directories are backed by the store. Only a run with no session and no workflow artifact is fully ephemeral.

The store is optional. A deployment that configures no AGENTA_STORE_* credentials runs agents normally, with mounts disabled: every run gets an ephemeral working directory inside its sandbox, and the table above no longer applies. See Enable the agent runner and durable store.

Next​