> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.modbox.run/llms.txt.
> For full documentation content, see https://docs.modbox.run/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.modbox.run/_mcp/server.

# AI Coding Agents

One of the most powerful use cases for Modbox is giving AI coding agents a fully isolated execution environment. Instead of running agent-generated code on your infrastructure, each agent gets its own sandbox — with its own filesystem, network, and process space.

## The problem without sandboxes

When an AI agent writes and runs code, a few things can go wrong:

* **Security** — agent-generated code can exfiltrate secrets, delete files, or call external APIs you didn't authorize
* **Isolation** — one agent's side effects can corrupt another agent's state
* **Cleanup** — leftover processes, temporary files, and installed packages accumulate
* **Resource limits** — a runaway loop can consume all available CPU or memory

Modbox solves all of this by giving each agent its own container with a configurable TTL.

## Architecture

```
Your Backend
    │
    ├── Agent 1 ──► Sandbox A (task_id: agent-abc123) ──► sandbox-a.modbox.run
    ├── Agent 2 ──► Sandbox B (task_id: agent-def456) ──► sandbox-b.modbox.run
    └── Agent 3 ──► Sandbox C (task_id: agent-ghi789) ──► sandbox-c.modbox.run
```

Each sandbox is completely isolated. Agents communicate with their sandbox via HTTP — sending code to execute and receiving output back.

## Example: AI coding agent with per-session sandboxes

```typescript
import { ModboxClient } from "modbox-sdk";
import { generateAgentCode } from "./your-llm-client";

const modbox = new ModboxClient({ token: process.env.MODBOX_API_TOKEN });

async function runAgentSession(userPrompt: string, sessionId: string) {
  // 1. Provision a fresh sandbox for this agent session
  const { sandboxId } = await modbox.provisionSandbox({
    taskId: `agent-${sessionId}`,
    imageId: process.env.CODE_EXEC_IMAGE_ID, // your code execution image
    ttlSeconds: 600, // auto-destroy after 10 minutes
    envVars: {
      SESSION_ID: sessionId,
    },
  });

  // 2. Wait for it to be ready
  await modbox.waitForSandbox({
    taskId: `agent-${sessionId}`,
    timeout: 30,
  });

  const sandbox = await modbox.getSandbox(sandboxId);

  // 3. Let the LLM generate code
  const code = await generateAgentCode(userPrompt);

  // 4. Execute the code inside the isolated sandbox
  const result = await fetch(`${sandbox.sandboxUrl}/execute`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ language: "python", code }),
  });

  const output = await result.json();

  // 5. Destroy the sandbox when done (or let TTL handle it)
  await modbox.destroySandbox({ taskId: `agent-${sessionId}` });

  return output;
}
```

```python
import httpx
import os
from modbox import ModboxClient

modbox = ModboxClient(token=os.environ["MODBOX_API_TOKEN"])

def run_agent_session(user_prompt: str, session_id: str) -> dict:
    task_id = f"agent-{session_id}"

    # 1. Provision a fresh sandbox
    modbox.provision_sandbox(
        task_id=task_id,
        image_id=os.environ["CODE_EXEC_IMAGE_ID"],
        ttl_seconds=600,
        env_vars={"SESSION_ID": session_id},
    )

    # 2. Wait for it to be ready
    modbox.wait_for_sandbox(task_id=task_id, timeout=30)
    sandbox = modbox.get_sandbox(task_id)

    # 3. Execute code inside the sandbox
    code = generate_agent_code(user_prompt)  # your LLM call

    response = httpx.post(
        f"{sandbox.sandbox_url}/execute",
        json={"language": "python", "code": code},
    )

    # 4. Clean up
    modbox.destroy_sandbox(task_id=task_id)

    return response.json()
```

## Multi-step agent loops

For agents that run multiple steps (like ReAct or tool-calling loops), keep the sandbox alive across steps:

```typescript
async function runMultiStepAgent(sessionId: string) {
  const taskId = `agent-${sessionId}`;

  // Provision once
  await modbox.provisionSandbox({ taskId, ttlSeconds: 1800 });
  await modbox.waitForSandbox({ taskId, timeout: 30 });
  const sandbox = await modbox.getSandbox(taskId);

  // Run multiple steps in the SAME sandbox (state persists between steps)
  for (const step of agentSteps) {
    const result = await fetch(`${sandbox.sandboxUrl}/execute`, {
      method: "POST",
      body: JSON.stringify({ code: step.code }),
    });
    // Feed output back to the LLM for the next step
    step.output = await result.json();
  }

  // Destroy when the agent finishes
  await modbox.destroySandbox({ taskId });
}
```

State persists within a sandbox session — installed packages, created files, and environment variables are all retained across multiple executions in the same sandbox.

## Recommendations

| Scenario                      | Recommended TTL |
| ----------------------------- | --------------- |
| Single code execution         | 60–120s         |
| Multi-step agent loop         | 600–1800s       |
| Long-running background agent | 3600s+          |
| Interactive dev session       | 7200s           |

Always set a TTL. Without it, a crashed agent can leave sandboxes running indefinitely, incurring costs.