Agentic Sandbox

The Agentic Sandbox provides secure, ephemeral Ubuntu containers for autonomous AI agents. Each sandbox is an isolated environment where agents can execute code, read and write files, and interact with the Gatana platform — all within a Kata Container virtual machine that is automatically cleaned up after a period of inactivity.

Sandboxes are designed for tasks like code generation and multi-step agent workflows where the agent needs a real Linux environment to operate in. One particular interesting case is developing and deploying runnable code servers to make re-use available through the Gatana Gateway.

Environment & Credentials

Each sandbox is a full Ubuntu 24.04 container with a comprehensive set of pre-installed tools:

The container runs as a non-root ubuntu user (uid 1000) with a home directory at /home/ubuntu.

Gatana CLI & Automatic Authentication

The Gatana CLI (gatana) is pre-installed globally. On startup, the sandbox automatically authenticates with your organization's Gatana instance using OIDC token exchange — no manual configuration required.

This means:

• A ~/.gatana.config file is written with connection details for the CLI (autmatically used by all Gatana SDK:s and CLI tools)
• The GATANA_API_KEY environment variable is set and inherited when using the exec API command (e.g. what LangChain Deep Agent uses)
• Credentials are automatically refreshed before they expire

Any command or script running inside the sandbox can immediately call Gatana APIs or use the CLI without setup.

Shell Access

There are two ways to get interactive shell access to a sandbox: the Web Terminal in the dashboard, Gatana CLI Tools and Direct SSH from any SSH client.

Web Terminal

Navigate to a sandbox's detail page in the Gatana dashboard. The integrated terminal connects automatically via WebSocket and provides a full xterm.js-based shell session. It supports window resizing and automatic reconnection.

Gatana CLI Tools

gatana sandbox sandboxId shell

Direct SSH

For access from your local terminal or an agent framework, you can connect via SSH using a short-lived session token.

Step 1 — Obtain a session token:

curl -X POST https://{org}.gatana.ai/api/v1/sandboxes/{sandboxId}/ssh-session \
  -H "Authorization: Bearer $GATANA_PAT"

This returns a JSON response containing a short-lived JWT (valid for 5 minutes):

{
  "token": "eyJhbGciOiJSUz..."
}

Step 2 — Connect using the token as your username:

ssh -o StrictHostKeyChecking=no -p 2222 "eyJhbGciOiJSUz..."@{gateway-host}

The SSH proxy authenticates the JWT, decrypts the per-sandbox SSH keypair, and bridges your session to the sandbox container. Each sandbox has a unique ed25519 keypair generated at creation time and encrypted at rest.

Deep Agent

Gatana sandboxes implement the LangChain Deep Agent sandbox backend interface. The gatana-langchain Python package provides a GatanaSandbox implementation that handles the full lifecycle automatically:

from gatana_client import GatanaClient
from langchain_anthropic import ChatAnthropic
from deepagents import create_deep_agent
from gatana_langchain import GatanaSandbox

client = GatanaClient()

with GatanaSandbox(client=client) as backend:
    agent = create_deep_agent(
        model=ChatAnthropic(model="claude-sonnet-4-20250514"),
        system_prompt="You are a coding assistant with sandbox access.",
        backend=backend,
    )

    result = agent.invoke({
        "messages": [
            {"role": "user", "content": "Create a Python script that prints the Fibonacci sequence and run it"}
        ]
    })
    print(result["messages"][-1].content)
# Sandbox is automatically destroyed when the `with` block exits.

For the full integration guide, see LangChain Deep Agents. The gatana-langchain package is available in the gatana-python repository.

API

The sandbox exposes three core operations through the Gatana API: exec, read file, and write file. All operations are proxied through the Gatana backend and require authentication.

Execute a Command

Run a shell command inside the sandbox. The response is streamed as newline-delimited JSON (NDJSON).

curl -X POST https://{org}.gatana.ai/api/v1/sandboxes/{sandboxId}/exec \
  -H "Authorization: Bearer $GATANA_PAT" \
  -H "Content-Type: application/json" \
  -d '{"command": "python3 -c \"print(42)\"", "timeout": 30}'

Request body:

Response (NDJSON stream):

{"type":"stdout","data":"42\n"}
{"type":"done","exitCode":0}

Each line is a JSON object with type being one of stdout, stderr, done, or error. The done event includes the exitCode.

Read a File

Stream the contents of a file from the sandbox.

curl -X POST https://{org}.gatana.ai/api/v1/sandboxes/{sandboxId}/read-file?path=/home/ubuntu/output.txt \
  -H "Authorization: Bearer $GATANA_PAT" \
  --output output.txt

The file content is returned as application/octet-stream.

Write a File

Write content to a file in the sandbox. Parent directories are created automatically.

curl -X POST https://{org}.gatana.ai/api/v1/sandboxes/{sandboxId}/write-file?path=/home/ubuntu/input.txt \
  -H "Authorization: Bearer $GATANA_PAT" \
  -H "Content-Type: application/octet-stream" \
  --data-binary @local-file.txt

The request body is written directly to the specified path.

Lifecycle & Limits

Creating a Sandbox

Via the dashboard: Navigate to Sandboxes in the sidebar and click Create Sandbox.

Via the CLI

gatana create sandbox

Destroying a Sandbox

Via the dashboard: Open the sandbox detail page and click Destroy.

Via the CLI

gatana delete sandbox sandboxId

Sandboxes that have been inactive for longer than the timeout are automatically destroyed. All sandbox activity is available in the audit log at GET /api/v1/sandboxes/{sandboxId}/audit-logs.