> ## 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 Blaxel, Unikraft Cloud, or Daytona
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`](/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.
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](/organization/secrets) first.
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,
"...": "..."
}
```
1. On the **Machines** page, click **New pool** and choose Blaxel, Unikraft, or Daytona.
2. Name the pool and select its provider credential secret. Use **New secret** to create one without leaving the dialog.
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 grant the pool to projects, then create it.
After creation, use the pool's row to edit, grant, or delete it.
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.
```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`.
On the pool's row, click **Grant to project** and select the project. Open the advanced section to set optional project limits and environment variables.
You can also open the project's **Grants** page, select **Machines**, and click **Grant pool**. The same page lists existing grants; click **Delete grant** 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.
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).