> ## Documentation index
> Fetch the complete index at: https://maritime.sh/llms.txt
> Setup procedure for AI agents (install, sign in, deploy, verify): https://maritime.sh/agents.md
> This page as HTML: https://maritime.sh/docs/persistent-sandboxes

# Agent Boxes

Agent boxes

An agent box is a persistent Linux machine that keeps its files. Each one is its own Firecracker micro-VM with its own disk. It
sleeps when idle and wakes in about a second when you run a command or touch a file. It costs $1 a
month per 2 GB of memory, awake or asleep, with unlimited awake hours.

## At a glance

| | |
| --- | --- |
| **What it is** | A Linux micro-VM that keeps `/data` until you delete it. It sleeps when idle and wakes in about a second. |
| **Use it for** | A workspace per end user, a coding agent that works on a repo for days, any agent you host. |
| **Use something else when** | Nothing should outlive the run: [Sandbox](https://maritime.sh/docs/ephemeral-sandboxes). A batch: [Swarm](https://maritime.sh/docs/swarms). A screen: [Linux desktop](https://maritime.sh/docs/computers). |
| **Start it** | The Agents page, by picking a template, `maritime create NAME --template zeroclaw`, or `agents.provision` in the SDK. |
| **Lifecycle** | Awake while used, asleep after an idle period (`--idle`), woken by any command, file call, message or trigger. Deleted only by you. |
| **Price** | $1 a month per 2 GB of memory, awake or asleep, billed per second over a 730-hour month (2 GB is $1, 4 GB is $2, 8 GB is $4). Unlimited awake hours. 5 GB of disk included; more disk is $0.08 per GB-month. |
| **Limits** | 2 GB RAM and 5 GB disk by default, up to 8 GB and 100 GB self-serve. `exec` 60 seconds attached, 3,600 detached. 100 MB per file. |
| **Related** | [How Maritime works](https://maritime.sh/docs/how-it-works), [SDK: agents](https://maritime.sh/docs/sdk/agents), [Images](https://maritime.sh/docs/images). |

## What runs today

An agent box is the Maritime machine an agent runs in. You create it in the dashboard, or with
the CLI or SDK, then run commands with `exec` and move files with the files API.

## From the dashboard

To create an agent box, open the [Agents](https://maritime.sh/agents) page and pick a template.
The new agent box appears in the list on that page.

## When to use it

- A workspace per end user that must keep its files, repos and installed tools between visits.
- A coding agent that clones a repo once and works on it over days.
- Anything you would otherwise rebuild from scratch on every request.

For one task that should leave nothing behind, see
[Sandboxes](https://maritime.sh/docs/ephemeral-sandboxes). For a machine with a screen,
see [Linux desktops](https://maritime.sh/docs/computers).

## Example

**CLI**

```bash
maritime create my-box --template zeroclaw

# exec takes the machine's id, not its name
maritime status my-box --json --select id

maritime exec AGENT_ID --body-json '{"command": "git clone https://github.com/acme/app /data/app"}' --json
maritime exec AGENT_ID --body-json '{"command": "ls /data/app"}' --json
```

**TypeScript**

```typescript
import { Maritime } from 'maritime-sdk'

const maritime = new Maritime({ apiKey: process.env.MARITIME_API_KEY })

// Idempotent on externalId: the same user always gets the same machine.
const box = await maritime.agents.provision({
  externalId: 'u_123',
  name: 'box-u_123',
  template: 'zeroclaw',
})

const run = await maritime.agents.exec(box.id, ['ls', '/data'])
console.log(run.exitCode, run.stdout)
```

**Python**

```python
from maritime import Maritime

client = Maritime()  # reads MARITIME_API_KEY

box = client.agents.provision("u_123", "box-u_123", template="zeroclaw")

run = client.agents.exec(box["id"], ["ls", "/data"])
print(run["exitCode"], run["stdout"])
```

A new machine boots in the background; a returning user's machine is already there. Commands and
file calls wake a sleeping machine on their own, so you never wake it by hand. The REST routes,
detached commands and cancellation are in
[REST API: Run a command](https://maritime.sh/docs/api#exec).

## Lifetime

- Everything under `/data` is kept until you delete the machine.
- After an idle period the machine sleeps. On micro-VM hosts the process is snapshotted and resumed,
  not restarted. Set the idle time with `--idle` (seconds) on `maritime create`.
- It is billed per second over a 730-hour month, awake or asleep: $1 a month per 2 GB of memory
  (2 GB is $1, 4 GB is $2, 8 GB is $4). Awake hours are unlimited. 5 GB of disk is included; more
  disk is $0.08 per GB-month.
- Waking takes about a second, on any command, file call, message or trigger.
- Deleting the machine deletes its disk.

```bash
maritime create my-box --template zeroclaw --idle 600 --disk 20
maritime delete my-box --yes
```

## Limits

- 2 GB RAM and 5 GB SSD by default; self-serve up to 8 GB RAM and 100 GB SSD.
- `exec`: 60 seconds attached by default, 3,600 seconds detached; each output stream keeps its
  last 262,144 characters.
- File transfers: 100 MB per file.
- A machine counts toward your plan's awake-at-once limit only while it is awake.

Every number is in [Limits & errors](https://maritime.sh/docs/limits); plans and prices are in
[Billing & plans](https://maritime.sh/docs/billing).

## Related

- [Sleep and wake](https://maritime.sh/docs/how-it-works#sleep-and-wake)
- [SDK: agents, files and exec](https://maritime.sh/docs/sdk/agents)
- [Env vars & sizing](https://maritime.sh/docs/configuration#resource-limits)
- [Images](https://maritime.sh/docs/images)