Machine pools

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.
Bring your own provider — connect your Blaxel, Unikraft Cloud, Daytona, Modal, Freestyle, Tenki, Arker, boxd, or CreateOS 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 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 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 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.
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. Blaxel, Daytona, Modal, Unikraft, Freestyle, Tenki, Arker, boxd, and CreateOS 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

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 first.

API
Dashboard

The examples assume the client, $ORG/orgID, and $PROJ/projectID setup from the quickstart.A Blaxel pool:

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

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
  }'

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,
  },
})

{
  "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,
  "...": "..."
}

Every pool requires max_total_machines. Resource requirements then depend on the provider; see Sandbox providers.

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
Dashboard

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

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" }
  }'

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' },
  },
})

{
  "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.

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

The pool provides the defaults.
The project grant can narrow or override those defaults.
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

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 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.

Full schema and playground: Create machine pool · Update machine pool · Pool grants.

Get started

Examples

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Default machine environment

What persists

Runtime protection

Create a pool

Grant a pool to a project

Use it from a config

​Default machine environment

​What persists

​Runtime protection

​Create a pool

​Grant a pool to a project

​Use it from a config

Default machine environment

What persists

Runtime protection

Create a pool

Grant a pool to a project

Use it from a config