AgentsAgent Runtime

Agent Runtime

Beta feature. Agent Runtime is in Beta and requires the Agent Sandbox controller.

Agent Runtime gives an agent a dedicated runtime: its own container, running a coding agent such as Claude Code or Codex. You get a live terminal, and the files persist. Send follow-ups and continue later with the same files.

Agent Runtime becomes available when your Kubernetes cluster serves the Agent Sandbox API. It needs persistent storage and the Agent Sandbox controller. See Setup.

A run uses the agent's instructions, tools, skills, and permissions. Its model calls go through the LLM Proxy and its tools through the MCP Gateway, so logs, guardrails, and cost limits apply.

The Create Agent page with Claude Code, Codex, OpenCode, Hermes, OpenClaw, Grok Build, and Kimi Code under Agent Runtimes

Create an Agent With a Dedicated Runtime

You can pick the runtimes an administrator lets you use, in addition to needing access to create or edit the agent. See who can use each runtime. Ordinary edits preserve an existing runtime, and read and run access is unchanged.

  1. Go to Agents and click Add Agent.
  2. Under Agent Runtimes, pick Claude Code, Codex, OpenCode, Hermes, OpenClaw, Grok Build, or Kimi Code. The agent opens prefilled.
  3. Review Runtime on the Configuration step. An attention icon marks a setting you must fix. Hover over it to see what to change.
  4. Click Create and run, or Continue setup to add tools, skills, and knowledge first.

The Configuration step with Claude Code selected in the Runtime picker

Already have an agent? Open it, turn on Dedicated runtime on its Agent Runtime tab, and click Save changes.

From a connected client, ask your agent to create one. create_agent takes the same choice as runtime: { "template": "claude-code" }, or a custom image. list_llm_models finds a model to pin.

Choose and Order Agent Runtimes

With organizationSettings:update, go to Settings → Agents → Runtimes to choose the agents offered during creation.

  1. Choose Add runtime to add a choice, or remove one with its … → Remove from list action.
  2. Drag the rows into your preferred order. You can also focus a row's reorder handle and use the arrow keys.

Each change saves as you make it. The Create Agent cards and Configuration runtime choices follow the order. Removing a choice preserves existing agents and their runtime configuration.

Set a Runtime's Settings

Decide once how a runtime's agents start, such as whether Claude Code bills each person's Claude subscription or a company API key. This uses organizationSettings:update.

  1. Go to Settings → Agents → Runtimes, open a runtime's ⋯ menu, and click Edit runtime.
  2. Under Runtime settings, set its defaults. A built-in runtime has Claude account (Claude Code only), run limits, and tiers. A custom runtime also has its image, protocol, and follow-up delivery.
  3. Click Save runtime.

Saved settings apply to agents created afterwards. To bring existing agents up to date, reopen the runtime: Existing agents shows how many still use older settings, and Update gives them the saved ones.

  • Each agent keeps its own environment, credentials, ports, and model.
  • An update is refused, naming the agents, when the new settings would no longer work with an agent's model. Change that agent's model first.

Choose Who Can Use Each Runtime

Try a runtime with a pilot team before offering it to everyone, and decide who may change its settings on their agents. Open the runtime's Edit runtime dialog and set Who can use it under General:

  • Can use: create agents on the runtime. They take its settings and can't change them.
  • Can use and configure: create agents on it and change its settings on those agents.
  • Full access: also change who can use it.

Admin and Platform Admin have full access to every runtime, and a new custom runtime starts with only them. To set access for all runtimes at once, use Permissions on the Runtimes page.

  • Running an image that isn't one of your runtimes needs Can use and configure on every runtime.
  • Running or chatting with an existing agent is decided by the agent's own permissions, not the runtime's.

Update the Image

Built-in coding agent images use the deployment's current catalog image unless pinned by digest. When the image reference changes, your next follow-up restarts the Agent on that image and keeps your files.

If you change a custom image or the Privileged mode setting, which grants access to the host system, start a new run. Existing files are kept until their retention deadline.

Models and Credentials

Each run gets a temporary virtual key. Provider keys stay in Archestra.

  • Claude Code: your Claude Pro or Max subscription, or an API key for Anthropic, Amazon Bedrock, or Anthropic on Vertex AI.
  • Codex: your ChatGPT subscription, connected under Model Providers. An OpenAI API key does not replace it.
  • Grok Build: your SuperGrok subscription, connected under Model Providers, or an xAI API key. Pick an xAI model, such as grok-4.7.
  • Kimi Code: a Kimi Code membership key, added as a Kimi Code key under Model Providers, for yourself or shared with a team. Pick a Kimi Code model, such as k3.1-pro.
  • Other agents: any model provider configured in Archestra.

What to know:

  • Each person connects their own Claude, ChatGPT or SuperGrok subscription before their first run. Subscription usage, Kimi Code included, shows in the logs, but it does not count toward cost limits.
  • Claude subscription runs use Opus unless you select another Model. Claude account default follows Claude Code's choice for your account.
  • Tools run with the permissions of the person who started the run.

Clone a Private GitHub Repository

Give a built-in coding agent a GITHUB_TOKEN, and it can clone, commit, push, and open pull requests as that token's GitHub account.

  1. Save a GitHub token in Credentials, with access to the repository. Cloning needs read access to repository contents; pushing needs write access.
  2. Open the agent's Agent Runtime tab. Under Environment, click Add variable.
  3. Set Key to GITHUB_TOKEN and Type to Secret. Under Secret source, select your saved credential.
  4. Save the agent, start a new run, and ask it to clone the repository, make a change, and open a pull request. The pull request's commits show the token's GitHub account as their author. If GitHub rejects the token, the run stops before the agent starts.

What to know:

  • For a token used only by this agent, choose Resource-specific secret instead. Secret values are provided after saving; turn on Required variable to have Chat prompt for a missing value before a run.
  • Accept credentials from a connected client controls credential transfers during handoff. It is not required for secrets configured under Environment.
  • The built-in images include Node.js, Python, Rust, and PostgreSQL with pgvector. To compile code with another toolchain, such as Go, extend the agent image.

Run a Task

Select the agent in Chat or in a Project and send a task. This starts a run: a container that works on your task. Follow-ups continue the same run. The live terminal opens and shows startup progress. Attach files before you send, and the agent reads them in its container.

  • Leave and come back: the run keeps working. Reopen it from the sidebar and send a follow-up.
  • Past runs: the agent's Runs tab lists live and finished runs. Select a run to open it, then select the Open full view expand icon for the larger terminal and run controls. For a retained run you started, select Resume to reopen it without sending a message.
  • Stop a run: the person who started it selects Stop in Chat or in the open run, or Stop run on its row in the Runs tab. Its saved files and history stay, so you can resume it later.
  • Delete a run: after a run ends, the person who started it selects Delete run on its row, or More run actions → Delete run in the open run. Deleting a run permanently removes its history, output, and saved files.
  • Several runs at once: on the Runs tab, select the runs you started. Then choose Stop, Delete saved files, or Delete. Stop acts on live runs. The other two act on finished runs. Delete saved files frees the storage of those runs and keeps their history.
  • Copy text: select Select text to copy text with the browser. Select Type to use the running app's controls again.
  • Ctrl+C: in Type mode, Archestra asks you to confirm before it sends Ctrl+C. Ctrl+C stops the agent's turn, and a second one can close the agent. The audit log records who attached to the terminal and when they sent Ctrl+C.
  • Follow-ups reach the agent between its turns. To type them into its terminal instead, set Steering to Terminal input on the Agent Runtime tab.
  • Open a web app: for a run you started, select Open full view, then More run actions → View connection details for the agent's port forwarding command.

What to know:

  • Only the person who started a run can type in it. Share the run to give others read-only access. Project members and agent administrators can read it without a share.

How Long a Run Lasts

  • An idle run pauses. Its files stay. Shell processes and development servers stop, so restart them when you resume.
  • A run expires after its maximum duration. Its history stays, but its files go. Push your work to a repository or download it first.
  • Stopping a run keeps its files. Deleting its container and storage removes them.

Limits

Limits protect your cluster and budget by capping runtime duration, idle time, spend, and container compute. Configure them under Limits on the agent's Agent Runtime tab. Blank fields inherit deployment defaults.

SettingWhat It Does
Idle timeoutPauses the run when it finishes a task and receives no follow-up within this time.
Maximum durationStops the run after this time, even mid-task, and deletes its files. Follow-ups do not extend it.
Metered LLM budgetBlocks metered model calls once the run reaches this spend. Subscription usage does not count.
Default tierSets the container size for standard runs from your organization's runtime tiers.
Scaleup tierSets the largest tier a run can request. Choose Disable autoscaling to disable scaling up.

When starting a run through start_agent_run or POST /api/agents/{id}/runs, you can pass custom limits. You can request stricter limits or a different tier, either by name or by minimum compute (min_cpu and min_memory_gib). A tier chosen by minimum compute never has a smaller workspace than the agent's default tier. Requests exceeding the agent's configured limits fail with the allowed tiers named.

A run that needs more compute starts a new run of the same agent at a larger tier and hands over its workspace. Setting Scaleup tier to Disable autoscaling disables scaling up. The agent runtime instance receives instructions that scaling is disabled, and scaleup attempts fail with a non-retriable error. A caller outside the agent's runs, such as a CI job, that asks for more than the agent's tier is told which tiers the agent can use. It can then start the run at the agent's tier.

Inside a container, ARCHESTRA_AGENT_RUNTIME_TIERS lists the allowed tiers with their CPU, memory, and workspace size. When the requested tier has no ready warm container, Archestra serves the run from the next larger tier within the scaleup limit, unless that tier has a smaller workspace. Runs never start below their requested tier.

Network Access

Unless an administrator sets a policy, a run can reach the public internet. To limit it, set a network egress policy on the agent's environment, or give the agent its own policy.

What to know:

  • A strict policy can break a task. Allow the repositories, package registries, and services the task uses.
  • A continued run picks up the current policy.

Guardrails in a Run

Guardrails check each tool call and tool result inside the run.

  • Delegated runs get their parent's restrictions before work starts. Follow-up instructions keep them. An answer crosses the guardrail check before another agent gets it.
  • Review: a run has no person at hand. By default, a call that needs human approval waits. Set Human approval under Break the glass in Settings → Guardrails to Waive in unattended sessions to let it run anyway and approve a plan that needs one for the agent. Each waiver records a yell in the Yells tab, and with the default Yell tool setting that yell also turns Guardrails off for the run's session. With the default, the review shows in the run's live terminal as the agent's own question card or form, and only the run's owner approves or denies it there. Client permission settings cannot approve it.
  • File downloads: a protected transfer checks the pinned file content before it returns a download command. It refuses a file that needs changes or that passes the protected export limit. The session owner can still download directly.
  • Old sessions: turning on Guardrails does not protect work that started before. Start a new session. Guardrails do not replace filesystem or network sandboxing.

Start Runs From Elsewhere

  • Remote Agents: hand work off from Claude Code or another connected agent, and bring it back.
  • A coordinator agent: add the agent as a subagent. The coordinator keeps answering while the run works. This also covers messaging channels: the result returns to the original thread.
  • Messaging channels: a message to the agent in Slack, Microsoft Teams, or Telegram starts a run. The bot replies with a link to the run, then posts the result in the thread. A follow-up from the same person continues their run.
  • Email: an email to the agent starts a run. The result returns in the thread when replies are on.
  • A2A: A2A clients start runs and continue them with the same contextId. Client-credentials OAuth applications cannot use Agent Runtime, even when bound to a service account. Use a permitted service-account API key or a user credential instead. See A2A.
  • Scripts and CI: with a permitted service-account API key or user credential, a script starts a run with start_agent_run through an MCP Gateway and polls get_agent_run. The run ends when the agent finishes. A failed run says whether to start again: see Read Why a Run Failed. Continue the saved workspace with steer_agent_run.

Read Why a Run Failed

A failed run carries a stable failure.code, so a script can retry or stop without parsing the message.

CodeRetryWhat happened
launch.kubernetes_unavailableYesThe Kubernetes API was overloaded or unavailable.
launch.kubernetes_rejectedNoKubernetes refused the run's objects.
launch.controller_missingNoThe cluster has no Agent Sandbox controller.
launch.misconfiguredNoThe agent's settings or the caller's credentials do not allow a start.
launch.capacity_timeoutYesThe pod did not start or resume in time.
launch.credentials_timeoutYesThe run's credentials did not reach the pod in time.
pod.evictedYesKubernetes evicted or preempted the pod.
pod.oom_killedNoThe run reached its tier's memory limit, and the kernel killed it.
pod.workspace_fullNoThe agent filled its workspace volume. Ask an administrator for a larger volume.
pod.image_pullNoThe image could not be pulled.
pod.failedNoThe pod failed for another reason.
turn.interruptedYesThe pod was replaced while the agent worked. The turn is not repeated.
turn.recording_failedYesThe terminal recording stopped, so the turn stopped.
turn.process_exitedNoThe agent exited before it reported a result.
turn.exit_statusNoThe agent exited with an error and gave no reason.
budget.exceededNoThe run spent its Metered LLM budget.
run.settings_changedNoThe agent's image or host access changed. Start a new run.
run.resume_refusedNoThe saved workspace cannot take this turn.
run.workspace_busyYesAnother turn took the saved workspace first.
run.workspace_missingNoThe workspace was deleted while the agent worked.
run.deadline_exceededNoThe workspace reached its retention deadline.
run.unknownNoNo other code applies.
image.<code>DependsThe agent's image reported this code. Maintained images mark rate limits, provider outages, and proxy or tool startup failures as retriable.

What to know:

  • failure.retriable is true when a new run of the same agent is likely to succeed without a change.
  • failure is null on a run that did not fail, and on a failed run with no code.
  • Under Guardrails, get_agent_run withholds the status reason but still returns the code. GET /api/agent-runs/:taskId also returns failure.message, the same text as statusReason.

Troubleshooting

  • A run does not start: see Setup troubleshooting.
  • A run ends with a pod failure: open Failed details for the Kubernetes pod name, failure reason, and container exit code when available. Share these details with your cluster operator; for example, OOMKilled identifies a memory termination and Evicted includes Kubernetes' eviction message.
  • A run ends with pod.oom_killed: the run used all the memory of its runtime tier. Failed details names the memory limit, the tier, and when the kernel killed the run. Start the run again at a larger tier, or have the agent run type checks, test suites, and builds one at a time and with fewer workers.
  • A run ends with pod.workspace_full: the agent filled its workspace volume, which holds the home directory and, for privileged agents, the Docker data. Failed details shows how much of the volume was used. Start a new run after an administrator gives the agent's runtime tier a larger Workspace size. A tier with no size uses ARCHESTRA_AGENT_RUNTIME_WORKSPACE_STORAGE_SIZE. Exit code 77 means the volume refuses writes for another reason, such as a read-only or failing volume: ask your cluster operator to check it.
  • A model call fails with a Guardrails error: the message says what to do, and the status says who.
    • 400: the conversation holds content Guardrails cannot store, such as binary tool output. Rewind past it or start a new conversation.
    • 409: the conversation cannot continue. Start a new one.
    • 500 with x-should-retry: false: an administrator must fix the policy or the deployment setting the message names, or report the reference it carries.
    • 503: a short outage. The client retries on its own.
  • A model call fails with HTTP 400 and names X-Archestra-Runtime-Binding: the agent's image does not send the run headers. Rebuild it on a current maintained image, then start a new run.
  • Find a run's traffic: LLM Proxy Logs and MCP Gateway Logs show the run ID. For health metrics, see Agent Runtime Health.

Explore