MetorialDocs

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.

What you'll learn

  • What machines, images, disks, and firewalls are
  • How to install the CLI and the SDKs
  • Where to go next

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.

Rendering diagram…

Install the tools

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

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:

npm install metorial

The SDKs authenticate with an API key.

Guides

Run your first machine

Create a machine, run a command, and clean up.

Configure a machine

Pick a size and region, and set the environment and startup commands.

Lifecycle, pausing, and hibernation

Pause idle machines, hibernate them, and run hooks on every transition.

Disks

Keep data across machines with attachable disks.

Custom images

Build your own image from a Dockerfile.

Connect with the CLI

Open a shell and transfer files from your terminal.

Connect with the SDK

Run commands, manage files, and call ports from code.

Networking

Expose ports, issue access tokens, and restrict outbound traffic.

Monitoring and debugging

Read logs, events, errors, and resource usage.

Wire protocol

Build your own client for exec, shell, and files.