# Sandbox



Sandbox provides secure, isolated containers for executing shell commands.

<Card title="Agentic Sandbox Tools" icon="terminal" href="/tool/bash_tools">
  Give your agent command execution with pre-built tools.
</Card>

## Quick Start [#quick-start]

<Steps>
  <Step title="Create a sandbox">
    <CodeGroup>
      ```python title="Python"
      import os
      from acontext import AcontextClient

      client = AcontextClient(api_key=os.getenv("ACONTEXT_API_KEY"))
      sandbox = client.sandboxes.create()
      ```

      ```typescript title="TypeScript"
      import { AcontextClient } from '@acontext/acontext';

      const client = new AcontextClient({
          apiKey: process.env.ACONTEXT_API_KEY,
      });
      const sandbox = await client.sandboxes.create();
      ```
    </CodeGroup>
  </Step>

  <Step title="Execute commands">
    <CodeGroup>
      ```python title="Python"
      result = client.sandboxes.exec_command(
          sandbox_id=sandbox.sandbox_id,
          command="echo 'Hello!' && python3 --version"
      )
      print(f"stdout: {result.stdout}")
      print(f"exit_code: {result.exit_code}")
      ```

      ```typescript title="TypeScript"
      const result = await client.sandboxes.execCommand({
          sandboxId: sandbox.sandbox_id,
          command: "echo 'Hello!' && python3 --version",
      });
      console.log(`stdout: ${result.stdout}`);
      console.log(`exit_code: ${result.exit_code}`);
      ```
    </CodeGroup>
  </Step>

  <Step title="Kill sandbox">
    <CodeGroup>
      ```python title="Python"
      client.sandboxes.kill(sandbox.sandbox_id)
      ```

      ```typescript title="TypeScript"
      await client.sandboxes.kill(sandbox.sandbox_id);
      ```
    </CodeGroup>
  </Step>
</Steps>

## Disk Integration [#disk-integration]

Transfer files between disk and sandbox:

<Steps>
  <Step title="Setup">
    <CodeGroup>
      ```python title="Python"
      from acontext import FileUpload

      disk = client.disks.create()
      sandbox = client.sandboxes.create()

      # Upload file to disk
      client.disks.artifacts.upsert(
          disk.id,
          file=FileUpload(filename="input.txt", content=b"Line 1\nLine 2"),
          file_path="/input/"
      )
      ```

      ```typescript title="TypeScript"
      import { FileUpload } from '@acontext/acontext';

      const disk = await client.disks.create();
      const sandbox = await client.sandboxes.create();

      // Upload file to disk
      await client.disks.artifacts.upsert(disk.id, {
          file: new FileUpload({
              filename: "input.txt",
              content: Buffer.from("Line 1\nLine 2"),
          }),
          filePath: "/input/",
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Download to sandbox">
    <CodeGroup>
      ```python title="Python"
      client.disks.artifacts.download_to_sandbox(
          disk_id=disk.id,
          file_path="/input/",
          filename="input.txt",
          sandbox_id=sandbox.sandbox_id,
          sandbox_path="/workspace/"
      )
      ```

      ```typescript title="TypeScript"
      await client.disks.artifacts.downloadToSandbox(disk.id, {
          filePath: "/input/",
          filename: "input.txt",
          sandboxId: sandbox.sandbox_id,
          sandboxPath: "/workspace/",
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Process in sandbox">
    <CodeGroup>
      ```python title="Python"
      client.sandboxes.exec_command(
          sandbox_id=sandbox.sandbox_id,
          command="wc -l /workspace/input.txt > /workspace/output.txt"
      )
      ```

      ```typescript title="TypeScript"
      await client.sandboxes.execCommand({
          sandboxId: sandbox.sandbox_id,
          command: "wc -l /workspace/input.txt > /workspace/output.txt",
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Upload result to disk">
    <CodeGroup>
      ```python title="Python"
      client.disks.artifacts.upload_from_sandbox(
          disk_id=disk.id,
          sandbox_id=sandbox.sandbox_id,
          sandbox_path="/workspace/",
          sandbox_filename="output.txt",
          file_path="/output/"
      )
      ```

      ```typescript title="TypeScript"
      await client.disks.artifacts.uploadFromSandbox(disk.id, {
          sandboxId: sandbox.sandbox_id,
          sandboxPath: "/workspace/",
          sandboxFilename: "output.txt",
          filePath: "/output/",
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Clean up">
    <CodeGroup>
      ```python title="Python"
      client.sandboxes.kill(sandbox.sandbox_id)
      # Disk persists after sandbox is killed
      ```

      ```typescript title="TypeScript"
      await client.sandboxes.kill(sandbox.sandbox_id);
      // Disk persists after sandbox is killed
      ```
    </CodeGroup>
  </Step>
</Steps>

## Next Steps [#next-steps]

<CardGroup cols="2">
  <Card title="Disk" icon="hard-drive" href="/store/disk">
    Persistent file storage
  </Card>

  <Card title="Bash Tools" icon="terminal" href="/tool/bash_tools">
    Agent sandbox tools
  </Card>
</CardGroup>