# Sandboxes
URL: https://metorial.com/docs/build/sandboxes

Give your agents isolated Linux machines to run code, store files, and serve apps.

---

Sandboxes give your agents their own Linux machines. Start a machine in seconds, run commands and move files from the CLI or the SDKs, and let it pause or hibernate when it goes idle.

<PageIntro>
  <Learn>
    * What machines, images, disks, and firewalls are
    * How to install the CLI and the SDKs
    * Where to go next
  </Learn>
</PageIntro>

## How sandboxes fit together [#how-sandboxes-fit-together]

A sandbox setup has four resources:

* Machines are isolated Linux VMs. Each one has its own CPU, memory, and a writable root disk.
* Machine images decide what a machine boots with. Start from a managed image such as Debian, Node.js, or Python, or build your own from a Dockerfile.
* Disks store data that outlives a machine. Attach them to any machine in the same region.
* Firewalls control which hosts a machine can reach on the internet.

You also pick a region for every machine and a size (CPU and memory). Images and disks must be available in the machine's region.

<Mermaid
  chart="flowchart LR
  Image[&#x22;Machine image&#x22;] --> Machine[&#x22;Machine&#x22;]
  Disk[&#x22;Disk&#x22;] -->|mounted at /data| Machine
  Firewall[&#x22;Firewall&#x22;] -->|outbound rules| Machine
  Machine -->|&#x22;public port or access token&#x22;| Clients[&#x22;Your app or agent&#x22;]"
/>

## Install the tools [#install-the-tools]

Sandbox commands live in the `metorial-admin` CLI. Install it and sign in:

```bash
npm install -g @metorial/admin
metorial-admin login
```

Homebrew (`brew install metorial/tap/metorial-admin`) and the install script (`curl -fsSL https://cli.metorial.com/install.sh | bash`) work too.

To manage sandboxes from code, install the SDK:

<CodeBlockTabs defaultValue="TypeScript" groupId="language" mode="shell">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="TypeScript">
      TypeScript
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="Python">
      Python
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="TypeScript">
    <Shell>
      <Command>
        {`npm install metorial`}
      </Command>
    </Shell>
  </CodeBlockTab>

  <CodeBlockTab value="Python">
    <Shell>
      <Command>
        {`pip install metorial`}
      </Command>
    </Shell>
  </CodeBlockTab>
</CodeBlockTabs>

The SDKs authenticate with an [API key](/docs/build/api).

## Guides [#guides]

<Cards columns="2">
  <Card title="Run your first machine" href="/docs/build/sandboxes/quickstart">
    Create a machine, run a command, and clean up.
  </Card>

  <Card title="Configure a machine" href="/docs/build/sandboxes/machines">
    Pick a size and region, and set the environment and startup commands.
  </Card>

  <Card title="Lifecycle, pausing, and hibernation" href="/docs/build/sandboxes/lifecycle">
    Pause idle machines, hibernate them, and run hooks on every transition.
  </Card>

  <Card title="Disks" href="/docs/build/sandboxes/disks">
    Keep data across machines with attachable disks.
  </Card>

  <Card title="Custom images" href="/docs/build/sandboxes/custom-images">
    Build your own image from a Dockerfile.
  </Card>

  <Card title="Connect with the CLI" href="/docs/build/sandboxes/connect-cli">
    Open a shell and transfer files from your terminal.
  </Card>

  <Card title="Connect with the SDK" href="/docs/build/sandboxes/connect-sdk">
    Run commands, manage files, and call ports from code.
  </Card>

  <Card title="Networking" href="/docs/build/sandboxes/networking">
    Expose ports, issue access tokens, and restrict outbound traffic.
  </Card>

  <Card title="Monitoring and debugging" href="/docs/build/sandboxes/monitoring">
    Read logs, events, errors, and resource usage.
  </Card>

  <Card title="Wire protocol" href="/docs/build/sandboxes/wire-protocol">
    Build your own client for exec, shell, and files.
  </Card>
</Cards>