Omnara

Omnara runs coding agents on pooled machines. CreateOS is one of its machine pool providers, so an Omnara agent can get a CreateOS microVM instead of a shared container, with its own kernel and its own network identity.

The provider ships in Omnara itself. There is nothing to install on your side, you create a pool, point it at a CreateOS API key, and Omnara provisions machines through our API from then on.

A CreateOS machine pool, an agent launched on it, and a command run inside its microVM

At a glance

Provider name: createos
Requires: an Omnara organization and a CreateOS API key
Set once: a shape, a root filesystem, and capacity limits
Auth: the API key is stored as an org-owned secret in Omnara, not on your machine

Set up a pool

Create a CreateOS API key

In the CreateOS dashboard, open Profile Settings, go to API Keys, and create a key. Store it in Omnara as an org-owned secret rather than pasting it into a pool field.

Choose a shape and a root filesystem

The shape sets each machine's CPU and memory, for example s-2vcpu-4gb. Which shapes you can use depends on your plan, see Limits.

The root filesystem is the image each machine boots from. devbox:1 works as it is and already carries Python, Node.js, Bun, Go, Rust and Docker. For your own toolchain, build a template from a Dockerfile once and use the template's name instead.

Create the pool

On Omnara's Machines page, choose New pool, then CreateOS, and fill in the credential, shape, root filesystem, per-machine CPU and memory maximums, and capacity limits. The maximums must be at least as large as the shape.

Pool fields

Creating a pool through Omnara's API takes the CreateOS settings in two places. provider_config applies to the whole pool, and default_machine_provider_options sets the defaults for each new machine:

create-pool.json

{
  "name": "createos-pool",
  "provider": "createos",
  "provider_auth_secret_id": "sec_...",
  "default_machine_provider_options": {
    "shape": "s-2vcpu-4gb",
    "rootfs": "devbox:1",
    "sleep_after_ms": 300000
  },
  "max_machine_cpu": 2,
  "max_machine_memory_mb": 4096,
  "max_total_cpu": 20,
  "max_total_memory_mb": 40960,
  "max_total_machines": 10
}

shape names a CreateOS shape. Because the shape fixes the machine size, the CPU and memory defaults are optional, and the maximums must be at least the shape's size.
rootfs is required. Use a built-in root filesystem such as devbox:1, or the name of one of your templates.
sleep_after_ms is optional and turns on sleep when idle. Leave it out to keep machines awake.
startup_script, also in default_machine_provider_options, runs on each new machine before Omnara's daemon starts.
allowed_shapes and allowed_rootfses in provider_config restrict what a project or agent config may ask for.
region is optional. Leaving it empty lets CreateOS place the machine, which is usually what you want.

Idle machines

With sleep turned on, an idle machine pauses as a snapshot of its memory, processes and disk, and compute billing stops. When an agent needs it again it resumes in place, so there is no cold boot and no setup to run a second time.

Omnara's dashboard cannot turn sleep on yet. Set sleep_after_ms through its API.

Environment limits

Omnara passes environment variables into the machine, and CreateOS caps them. Plan for these when you write a startup script:

Limit	Value
Variables per machine, including the ones Omnara adds	64
Size of one variable	4 KiB
Total size of all variables	64 KiB
Startup script size	3,072 bytes

Only variable names made of letters, digits and underscores, and not starting with a digit, reach the startup script. Anything else is dropped silently.

Limitations

Sleep is API-only for now. Omnara's pool dialog does not expose sleep_after_ms.
The startup script budget is small. It shares the 64 KiB environment allowance with everything Omnara injects, which leaves about 3 KiB. Fetch a longer script instead of inlining it.
A root filesystem is mandatory. Unlike some providers there is no implicit default, so a pool without rootfs will not create machines.
Machine size comes from the shape. Raising Omnara's CPU or memory maximums above the shape does not give a machine more of either.