run_command. It can be a laptop on your desk, a VM in your VPC, a cloud sandbox created on demand or any other environment with access to a shell.
Every machine runs the same small daemon, omnarad, which connects outbound to the control plane. You do not need to open inbound ports, distribute SSH keys, or give Omnara a network path into your infrastructure.
Most importantly, the machine does not own the agent. Agents live in the control plane as event logs; machines are execution environments they can attach and release. Disconnecting a machine does not kill the agent.
Two ways to get one
The mounted storage example is the canonical BYO story.
Machine state
Every machine reports two independent states:lifecycle_statetracks whether the machine is being provisioned, active, being deleted, or deleted. It also reports provisioning and deletion failures.connection_statereports whether the machine is currentlyonline,asleep, oroffline.
active machine can be offline, for example when someone closes a laptop. New commands fail with a retryable error. A process may continue on the machine, but the agent cannot interact with it until the daemon reconnects. After a grace period, tool calls waiting on that process return a retryable machine_unreachable result.
A machine is available to an agent only when its binding is attached, its project grant still exists, its lifecycle is active, and its daemon is online or the machine is asleep and can be woken. The inspect_machine tool reports this as executable.
Who may use a machine
Machines and pools are org-level resources; projects get access through explicit grants: A machine grant lets a project’s agents use one specific machine. A pool grant lets them create machines from a pool, optionally with tighter limits and project-specific environment variables. Agent configs reference granted machines and pools by name inmachine_sources. Omnara checks access when the config is created and again when an agent launches.
Bindings: how an agent holds a machine
At launch, each BYO machine and each pool machine requested throughinitial_num_machines becomes an agent machine binding. Agents can create more pool machines later with create_machine.
A binding stores the working directory and environment for that agent. It also gets a short machine_ref, such as mchr-x7k2p3, which tools use to select the machine:
attached until released. Releasing a pool binding schedules its machine for deletion; releasing a BYO binding only detaches it from the agent. Archiving an agent releases all of its bindings. The command and process tools use these bindings.
Reading order
Connect a machine
Register a BYO machine and grant it to a project
Machine pools
On-demand capacity from Blaxel, Unikraft, or Daytona
Built-in tools
The command and process tools, from the agent’s point of view
Mounted storage example
A complete BYO walkthrough