Use several sandboxes in one session

By default a session has one instance of each ToolRegistry sandbox. Raise the sandbox’s maxInstances when an agent needs separate workspaces of the same kind in one conversation, for example one for a frontend and one for a backend, or one per parallel task.

Prerequisites

An AgentRuntime with spec.sandbox.enabled: true.
A ToolRegistry with a sandbox and a handler on it. See Running an MCP server locally and the sandbox reference.
A PromptPack prompt that lists the sandbox’s tools in tools. The model is offered only the tools the prompt lists.

Raise the sandbox’s instance cap

Set maxInstances on the sandbox:

apiVersion: omnia.altairalabs.ai/v1alpha1
kind: ToolRegistry
metadata:
  name: dev-tools
spec:
  sandboxes:
    - name: code
      class:
        name: codegen-default
        kind: ClusterSandboxClass
      maxInstances: 3
  handlers:
    - name: code
      type: mcp
      sandbox:
        name: code
        port: mcp
      mcpConfig:
        transport: sse
        endpoint: /sse
        toolFilter:
          allowlist: [Read, Write, Edit, Bash]

maxInstances caps one sandbox. The AgentRuntime’s spec.sandbox.maxPerSession caps the session’s total across every sandbox, and defaults to 1, so raise it to at least the same number:

spec:
  sandbox:
    enabled: true
    maxPerSession: 3

Each tool of every handler on the sandbox now has an optional sandbox argument. See Sandbox instances for the description the model sees and the rules for names.

What the agent does

The model passes a name with each call. A new name opens a new sandbox; a name it has used before reaches the same sandbox again. The other argument names depend on the sandbox image’s tool; these are illustrative:

{"command": "npm test", "sandbox": "frontend"}
{"command": "go test ./...", "sandbox": "backend"}

A file written in frontend is not visible in backend: they are separate pods built from the same class.

Check the sandboxes

List the session’s claims. Each has the handle <sandbox>/<name>:

kubectl get sandboxclaims -n <namespace> \
  -l omnia.altairalabs.ai/sandbox-session=<session-id> \
  -o custom-columns=NAME:.metadata.name,HANDLE:.spec.handle,PHASE:.status.phase

Limits

See Sandbox instances for what happens at the cap, and the AgentRuntime sandbox fields for maxPerSession, maxConcurrent and idleTimeout. A sandbox with a targetPath is limited to one instance.