Sandbox Execution¶

PrimeThink agents can execute shell commands in isolated, ephemeral sandboxes. Each agent turn gets its own sandbox that is provisioned on demand and destroyed when the turn ends.

Sandboxes run on one of two compute backends, chosen by your deployment:

Everything else on this page — the tool, its parameters, the in-sandbox environment, the preinstalled tooling and the security model — is the same on both. The differences are called out where they matter.

Overview¶

The sandbox provides agents with a secure, isolated environment to:

• Run shell commands (bash, Python scripts, etc.)
• Install and use command-line tools
• Process files and data in a disposable environment
• Execute code without affecting the host system

Key Properties¶

• Ephemeral: Each agent turn gets a fresh sandbox. Nothing persists between turns.
• Isolated: Concurrent agent turns (same chat, different chats) always get independent sandboxes and cannot share filesystem state.
• Lazy provisioning: The sandbox is only created on the first sandbox_exec call, not at agent invocation time. If the agent doesn't use the sandbox tool, no resources are consumed.
• Auto-cleanup: Sandboxes are destroyed when the agent turn ends. If that teardown ever fails to run, idle backstops reclaim the leftover sandbox — on Daytona, auto-stop (default 15 min idle) and then auto-archive (default 7 days); on Kubernetes, each per-turn sandbox also carries its own shutdown deadline. These are backstops, not the normal lifecycle.

How It Works¶

When the AI assistant uses the sandbox_exec tool:

1. First call: A sandbox is provisioned from PrimeThink's prebuilt Ubuntu image with a hidden ephemeral API key. The user is notified that the sandbox is starting.
2. Subsequent calls: The same sandbox is reused within the agent turn. Files and state from previous commands are still present.
3. Turn ends: The sandbox is destroyed and the ephemeral API key is disposed.

In-Sandbox Environment¶

The sandbox comes pre-configured with these environment variables:

The ephemeral API key (PT_TOKEN) inherits the user's role at creation time, allowing in-sandbox tools to call the PrimeThink API with the user's own permissions (it cannot exceed them). It also uses that role's API rate-limit tier, but draws from its own per-key budget so sandbox calls do not consume the user's interactive-session budget.

Preinstalled Tooling¶

The snapshot is prebuilt so a turn does not spend its time installing basics. It ships with:

Because Chromium is already present, an agent can drive a real browser from the sandbox — take screenshots, record traces, and reach a preview server it started on localhost in the same sandbox. Run it headless and keep any artifacts under /sandbox. Agents should not download additional browsers; the pinned build is the one that works in this environment.

Commands run as a non-root user that has passwordless sudo, so an agent can still install extra packages for the duration of the turn.

Usage¶

The sandbox is used by the AI assistant through natural conversation. Ask the assistant to run commands:

• "Run this Python script in a sandbox"
• "Install pandas and analyze this CSV data"
• "Execute ls -la in a sandbox"
• "Compile and run this C code"

Tool Parameters¶

The sandbox_exec tool accepts:

Tool Response¶

The tool returns JSON:

{
    "exit_code": 0,
    "stdout": "command output...",
    "truncated": false,
    "sandbox_id": "sb-abc123"
}

A non-zero exit_code indicates a command execution error, not a tool error — the assistant reads stdout to diagnose and fix the issue.

Configuration¶

Sandbox settings can be configured at the environment, group, or user level — and, for a value resolved during a chat, at the workspace or chat level too. The most specific level wins; see the settings hierarchy.

Choosing the backend¶

An unrecognised value is rejected rather than quietly falling back to the other backend, so a typo fails loudly instead of sending work somewhere unexpected.

Shared policy (both backends)¶

These keep their historical DAYTONA_-prefixed names but are honoured by both backends.

Daytona only¶

Kubernetes only¶

Cluster credentials are deployment-level only and cannot be overridden by a group.

Enabling Sandboxes¶

To enable sandbox execution for a group on the default Daytona backend:

1. Obtain a Daytona API key
2. Configure DAYTONA_API_KEY as a group-level setting (or user-level for individual access)
3. Assign the sandbox capability to the agent

On a deployment running the Kubernetes backend, no provider key is needed — step 1 and 2 are replaced by the operator's cluster setup, and you only assign the capability.

Security¶

• Ephemeral API keys are hidden from user-facing API key listings and are automatically disposed on sandbox teardown
• Role inheritance — the ephemeral key captures the user's current role, so sandbox commands cannot escalate privileges
• Short-lived — API keys exist only for the duration of a single agent turn (seconds to minutes)
• Isolated execution — each sandbox is a separate container with no access to the host system or other sandboxes

Related Topics¶

• Capabilities - Managing agent capabilities
• Working with AI Agents - Agent configuration
• Tool Plugins - Developing custom agent tools