# 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](/content/docs/ephemeral-sandboxes/index.html). A batch: [Swarm](/content/docs/swarms/index.html). A screen: [Linux desktop](/content/docs/computers/index.html). |
| **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](/content/docs/how-it-works/index.html), [SDK: agents](/content/docs/sdk/agents/index.html), [Images](/content/docs/images/index.html). |

## 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](/content/agents/index.html) 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](/content/docs/ephemeral-sandboxes/index.html). For a machine with a screen, see [Linux desktops](/content/docs/computers/index.html).

## 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](/content/docs/api#exec/index.html).

## 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](/content/docs/limits/index.html); plans and prices are in [Billing & plans](/content/docs/billing/index.html).