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, or Daytona account and create a custom pool. You provide the API credential and choose the image or snapshot containing your tools and dependencies.

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

New organizations already have default pools granted to their first project. Check the Machines page 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:

Blaxel: memory default and maximums are required; CPU is not configurable.
Unikraft: CPU and memory defaults and maximums are required.
Daytona: CPU and memory maximums are required; defaults are optional because the snapshot defines the machine size.

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.

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

Get started

Agents

Inputs & events

Tools

Machines

Organization

Integrations

Examples

What persists

Runtime protection

Create a pool

Grant a pool to a project

Use it from a config

​What persists

​Runtime protection

​Create a pool

​Grant a pool to a project

​Use it from a config

What persists

Runtime protection

Create a pool

Grant a pool to a project

Use it from a config