> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Omnara

> Point an Omnara machine pool at your boxd organization and every agent gets its own machine that sleeps between turns.

<img src="https://mintcdn.com/azin/XrwBE5gH-2h4LJrE/images/boxd-x-omnara.png?fit=max&auto=format&n=XrwBE5gH-2h4LJrE&q=85&s=2de0433391eebfa8d60aaa565888ad50" alt="The banner shows the boxd.sh and Omnara logos with the line durable agents on machines that sleep between turns." width="2400" height="1640" data-path="images/boxd-x-omnara.png" />

[Omnara](https://omnara.com) is an open-source platform for running managed agents. It handles execution and state, and you choose the models, tools, and machines. boxd is a [first-class machine pool provider](https://github.com/omnara-ai/omnara/pull/521) next to Blaxel, Daytona, Modal, and Unikraft, so an Omnara org can connect its own boxd organization and run every agent on a boxd machine.

## How it works

Each Omnara machine is one boxd machine in your org. Between turns the Omnara daemon goes idle, and boxd puts the machine on standby once its network goes quiet. Memory, processes, and open sockets are kept on standby. When the agent needs the machine again, Omnara wakes it through the boxd API and the daemon is back online in 0.6 to 1.2 seconds.

Machines come in boxd's four sizes: 1 vCPU / 4 GiB, 2 vCPU / 8 GiB, 4 vCPU / 16 GiB, and 8 vCPU / 32 GiB. Save your tools in a [snapshot](/guides/snapshots) and every new machine is created from it.

## Set up a boxd pool

Create an API key fenced to the org your machines should run in, and store it as an Omnara org secret:

```bash theme={"theme":"github-dark"}
boxd auth keys create omnara --org <your-org>

npx omnara secrets create \
  --owner-kind org \
  --name boxd-api-key \
  --material-kind generic \
  --material-value "bxd_..."
```

Then create the pool with that secret. `sleep_after_ms` idles the daemon after a minute of inactivity, which lets boxd put the machine on standby:

```bash theme={"theme":"github-dark"}
npx omnara pools create \
  --name boxd-pool \
  --provider boxd \
  --provider-auth-secret-id sec_... \
  --default-machine-provider-options '{"sleep_after_ms": 60000}' \
  --default-machine-cpu 2 \
  --default-machine-memory-mb 8192 \
  --max-total-machines 10 \
  --max-total-cpu 20 \
  --max-total-memory-mb 81920 \
  --max-machine-cpu 2 \
  --max-machine-memory-mb 8192 \
  --json
```

The Omnara dashboard works too. On the **Machines** page, click **New pool**, choose boxd, pick the secret, and pick a size.

To create machines from your own snapshot, save one with `boxd snapshots save <machine> <name>` and pass `"snapshot": "<name>"` in the provider options. A machine created from a snapshot keeps the size of its source machine, so a configured size has to match it.

Omnara's [machine pool docs](https://docs.omnara.com/machines/pools) and [self-hosting configuration](https://docs.omnara.com/self-hosting/configuration) cover the rest, including `startup_script`, `auto_suspend_secs`, and runtime protection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.