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

# Machine pools

> On-demand machine capacity from Arker, Blaxel, boxd, CreateOS, Daytona, Freestyle, Modal, Tenki, or Unikraft Cloud

A machine pool lets Omnara create machines from a sandbox provider when an agent needs them.

Omnara gives you two ways to run pool machines:

* **Omnara-managed pools** — ready-to-use sandboxes. Omnara manages the sandbox provider account, credentials, and [default machine environment](#default-machine-environment).
* **Bring your own provider** — connect your Arker, Blaxel, boxd, CreateOS, Daytona, Freestyle, Modal, Tenki, or Unikraft Cloud account and create a custom pool. You provide the API credential and choose the image or snapshot containing your tools and dependencies. See [Sandbox providers](/machines/providers/overview) for each provider.

## Default machine environment

Machines from Omnara-managed pools run Ubuntu 24.04 as root, with common development tools preinstalled so agents can start working without installing them. The default working directory is `/workspace`. Custom pools and self-hosted deployments use the image or snapshot you choose.

| Category | Included |
| - | - |
| Languages | Python 3.12, Node.js 24, Go 1.27, C and C++ (gcc 13) |
| Package managers | pip, uv, npm, pnpm, Yarn |
| Build tools | make, cmake, ninja |
| Databases | PostgreSQL 16, Redis 7, SQLite |
| Command-line tools | `git`, `gh`, `jq`, `yq`, `rg`, `curl`, `wget`, `zip`, `sudo` |
| Python libraries | numpy, pandas, matplotlib, openpyxl, python-docx, python-pptx, pypdf |
| PDF tools | `pdftotext`, `pdftoppm`, `qpdf` |
| Browser automation | Playwright for Python with Chromium headless shell |

* `/bin/sh` is bash, so [`run_command`](/tools/built-in#run_command) accepts bash syntax with the default shell.
* `pip install` and `uv pip install --system` install into the system Python without a virtual environment.
* PostgreSQL and Redis are installed but not running. Create and start a PostgreSQL cluster with `pg_createcluster 16 main --start`.
* A `GITHUB_TOKEN` or `GH_TOKEN` [environment variable](/agents/configuration#machines) authenticates both `gh` and `git` to GitHub over HTTPS.

Agents can install other tools with `apt-get` or a language's package manager.

## What persists

A pool machine keeps its files, installed dependencies, and running processes across turns, including when the provider suspends and resumes it while idle.

Omnara deletes a pool machine when:

* The agent calls [`delete_machine`](/tools/built-in#delete_machine).
* The agent's config no longer includes that pool source.
* The agent is archived.
* The pool is deleted.
* Its configured idle-deletion period elapses.

Idle deletion waits until the machine has no queued or active process work. Process activity restarts the idle period.

A replacement starts from the pool's original image or snapshot.

The agent's conversation, event history, and uploaded artifacts remain in Omnara after the machine is deleted.

## Runtime protection

Runtime protection is an optional pool setting that defaults to disabled. When enabled, Omnara may delete a provider sandbox that remains running after its daemon becomes inactive. Out-of-band work that keeps a sandbox running without its daemon is therefore not supported on a protected pool.

Arker, Blaxel, boxd, CreateOS, Daytona, Freestyle, Modal, Tenki, and Unikraft pools support runtime protection. It does not apply to directly connected machines, and provider errors delay enforcement. The setting belongs to the pool and cannot be overridden by a project grant or agent config.

## Create a pool

> [!NOTE]
>
> New organizations already have default pools granted to their first project. Check the **Machines** page, with **All projects** selected in the project switcher, before creating one. Self-hosted deployments configure default pools separately.

For a custom pool, store the provider's API key as an org-owned [secret](/organization/secrets) first.

**API**

The examples assume the client, `$ORG`/`orgID`, and `$PROJ`/`projectID` setup from the [quickstart](/quickstart).

A Blaxel pool:

```bash CLI theme={null}
npx omnara pools create \
  --name sandbox-pool \
  --provider blaxel \
  --provider-auth-secret-id sec_hcyd5n6a2bfgik7mv4qtrwz3je \
  --provider-config '{"workspace": "acme-main"}' \
  --default-machine-provider-options '{"image": "sandbox/repo-agent:latest", "region": "us-pdx-1"}' \
  --default-machine-memory-mb 1024 \
  --default-cwd /workspace \
  --max-total-machines 10 \
  --max-total-memory-mb 10240 \
  --min-machine-memory-mb 1024 \
  --max-machine-memory-mb 1024 \
  --json
```

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/machine-pools" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sandbox-pool",
    "provider": "blaxel",
    "provider_auth_secret_id": "sec_hcyd5n6a2bfgik7mv4qtrwz3je",
    "provider_config": { "workspace": "acme-main" },
    "default_machine_provider_options": { "image": "sandbox/repo-agent:latest", "region": "us-pdx-1" },
    "default_machine_memory_mb": 1024,
    "default_cwd": "/workspace",
    "max_total_machines": 10,
    "max_total_memory_mb": 10240,
    "min_machine_memory_mb": 1024,
    "max_machine_memory_mb": 1024
  }'
```

```typescript SDK theme={null}
const pool = await sdk.createMachinePool({
  client,
  path: { orgID },
  body: {
    name: 'sandbox-pool',
    provider: 'blaxel',
    provider_auth_secret_id: 'sec_hcyd5n6a2bfgik7mv4qtrwz3je',
    provider_config: { workspace: 'acme-main' },
    default_machine_provider_options: { image: 'sandbox/repo-agent:latest', region: 'us-pdx-1' },
    default_machine_memory_mb: 1024,
    default_cwd: '/workspace',
    max_total_machines: 10,
    max_total_memory_mb: 10240,
    min_machine_memory_mb: 1024,
    max_machine_memory_mb: 1024,
  },
})
```

```json theme={null}
{
  "id": "mpo_a2bfgik7mv4qtrwz3jehcyd5n6",
  "name": "sandbox-pool",
  "provider": "blaxel",
  "default_machine_memory_mb": 1024,
  "default_machine_provider_options": { "image": "sandbox/repo-agent:latest", "region": "us-pdx-1" },
  "max_total_machines": 10,
  "max_total_memory_mb": 10240,
  "min_machine_memory_mb": 1024,
  "max_machine_memory_mb": 1024,
  "...": "..."
}
```

**Dashboard**

1. With **All projects** selected in the project switcher, open **Machines**, click **New pool**, and choose Arker, Blaxel, boxd, CreateOS, Daytona, Freestyle, Modal, Tenki, or Unikraft.
2. Name the pool, enter its workspace if the provider needs one, and select its provider credential secret. Use **New secret** to create one without leaving the dialog. The dialog then checks that the provider accepts it.
3. Enter the image or snapshot, provider settings, machine size, and capacity limits. You can also set a startup script, working directory, and environment variables.
4. Optionally pick projects under **Share with**, then create it.

After creation, use the pool's row to edit, share, or delete it.

Every pool requires `max_total_machines`. Resource requirements then depend on the provider; see [Sandbox providers](/machines/providers/overview).

## Grant a pool to a project

Pools belong to the organization. A project needs a grant to use one. The grant can use the pool defaults or set stricter capacity limits and project-specific environment variables.

**API**

```bash CLI theme={null}
npx omnara grant pools add \
  --machine-pool-id mpo_a2bfgik7mv4qtrwz3jehcyd5n6 \
  --max-total-machines 3 \
  --default-machine-env-overlay '{"DEPLOY_ENV": "staging"}' \
  --default-machine-secret-env-overlay '{"NPM_TOKEN": "sec_7jehcyd5n6a2bfgik7mv4qtrwz"}' \
  --json
```

```bash REST theme={null}
curl "$OMNARA_API/orgs/$ORG/projects/$PROJ/machine-pool-grants" \
  -H "Authorization: Bearer $OMNARA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "machine_pool_id": "mpo_a2bfgik7mv4qtrwz3jehcyd5n6",
    "max_total_machines": 3,
    "default_machine_env_overlay": { "DEPLOY_ENV": "staging" },
    "default_machine_secret_env_overlay": { "NPM_TOKEN": "sec_7jehcyd5n6a2bfgik7mv4qtrwz" }
  }'
```

```typescript SDK theme={null}
const grant = await sdk.createProjectMachinePoolGrant({
  client,
  path: { orgID, projectID },
  body: {
    machine_pool_id: 'mpo_a2bfgik7mv4qtrwz3jehcyd5n6',
    max_total_machines: 3,
    default_machine_env_overlay: { DEPLOY_ENV: 'staging' },
    default_machine_secret_env_overlay: { NPM_TOKEN: 'sec_7jehcyd5n6a2bfgik7mv4qtrwz' },
  },
})
```

```json theme={null}
{
  "id": "pmpg_2bfgik7mv4qtrwz3jehcyd5n6a",
  "machine_pool_id": "mpo_a2bfgik7mv4qtrwz3jehcyd5n6",
  "max_total_machines": 3,
  "default_machine_env_overlay": { "DEPLOY_ENV": "staging" },
  "default_machine_secret_env_overlay": { "NPM_TOKEN": "sec_7jehcyd5n6a2bfgik7mv4qtrwz" },
  "...": "..."
}
```

To manage existing grants, list the project's pool grants (`omnara grant pools list`), change a grant's overrides (`omnara grant pools edit {pool-grant-id}`), or revoke one (`omnara grant pools delete {pool-grant-id}`); the REST API and SDK expose the same list, update, and delete operations on `machine-pool-grants`.

**Dashboard**

On the pool's row on the organization **Machines** page, click **Share with project** and select the project. Open **Overrides** to set optional project limits and environment variables.

You can also open the project's **Machines** page and click **Share pool**. The page's **Shared machine pools** table lists existing shares; click **Stop sharing** to revoke one.

When Omnara creates a pool machine, it combines the machine size, working directory, environment variables, secret environment variables, and provider options from three places:

1. The pool provides the defaults.
2. The project grant can narrow or override those defaults.
3. The agent config can customize them for that agent.

Later values replace earlier ones. A project grant or agent config can remove an environment variable inherited from the pool by setting it to `null`. Pool and project limits remain hard constraints.

`delete_after_idle_minutes` follows the same override order. An unset grant or agent value inherits, `0` disables idle deletion at that level, and enabled values must be at least 5 minutes.

## Use it from a config

```yaml theme={null}
machine_sources:
  - machine_pool_name: sandbox-pool
    cwd: /workspace/my-repo
    machine_memory_mb: 1024      # within pool limits
    max_machines: 3              # this agent's own ceiling
```

By default, Omnara creates one machine at launch and allows one machine in total. Use `initial_num_machines` to control how many are created at launch and `max_machines` to set the total limit. The agent can call [`create_machine`](/tools/built-in#create_machine) until it reaches that limit.

`machine_cpu` and `machine_memory_mb` set the default size; where supported, the agent can override `cpu` and `memory_mb` per `create_machine` call within pool and project limits.

> [!NOTE]
>
> Full schema and playground: [Create machine pool](/api-reference/endpoints/machine-pools/create-machine-pool) · [Update machine pool](/api-reference/endpoints/machine-pools/update-machine-pool) · [Pool grants](/api-reference/endpoints/machine-pools/create-project-machine-pool-grant).


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