How to Use Omnara: The Beginner's Guide to the Open-Source AI Agent Platform

CodexFuse Team · 2026-11-02T18:46:55.609Z · 21 min read min read

Omnara is an open-source managed agent platform: define an agent in agent.yaml, launch it on any model and any machine, and steer it from a dashboard with approvals. This beginner's guide covers Omnara Cloud, self-hosting with Docker, and pricing.

Give a coding agent a machine and an API key and you immediately have two problems: you cannot see what it is doing, and you cannot stop it before it does something expensive or destructive. Learning how to use Omnara solves both at once. Omnara is an open-source managed agent platform: you describe an agent in a small YAML file, launch it on any model and any machine, then watch its tool calls stream into a dashboard where you can approve, deny, or redirect them in real time. This beginner's guide walks you through signing up for Omnara Cloud, launching your first agent with agent.yaml, steering it from the dashboard, setting approval rules, and self-hosting the whole platform with Docker when you want every byte of agent history in your own database. If you can edit a config file and run a terminal command, you can run agents as a service. If the agent side itself is new to you, start with this Claude Code beginner guide first — Omnara is the control plane that runs agents like Claude Code for you, around the clock.

What Is Omnara, Exactly?

Omnara is an open-source managed agent platform for running AI agents on any model and any machine, with tools, secrets, permissions, and streaming built in. Instead of a long-lived process on your laptop, each agent lives as a durable record in Postgres: you launch it through an API call, a CLI command, or the dashboard, and Omnara's workers run its loop, call the model, and execute tools on sandboxes or your own machines. You can use Omnara Cloud, or self-host the entire platform for free under Apache 2.0. The project describes itself as the open-source alternative to Claude Managed Agents and OpenAI's Agents API — the same "agents as a service" idea, but with your choice of models, machines, and where the data lives.

The repository is omnara-ai/omnara on GitHub, created in July 2025 and updated the day this guide was written. It carries 3,343 stars and 259 forks as of 2026-11-02, and the company's site says it is backed by Y Combinator. Omnara launched publicly around October 21–23, 2026, with a Show HN post that reached 114 points and 34 comments when captured by an independent write-up on October 28.

What Happened to the Old Omnara? (The pip install omnara Era)

The old Omnara is gone — if a tutorial tells you to run pip install omnara, it is describing a product that no longer exists in that form. The company's earlier product was a phone app for remote-controlling Claude Code and Codex sessions: it synced your terminal agent with a web dashboard and a mobile app so you could watch it and tap to approve requests from your phone. The founder said in the Show HN post that it relied on a laptop-hosted harness and simply stopped when the laptop closed. The new product runs agents in the cloud instead, and your laptop can now serve as just one of the agent's machines.

The practical consequence: the PyPI package named omnara is now a deprecated redirect whose own metadata says to install the current CLI with curl -fsSL https://omnara.com/install.sh | bash. Directory profiles like toolify.ai still describe the earlier "AI agent command center" and still recommend pip install omnara — treat those install instructions as stale. Everything in this guide targets the current platform: the omnara npm CLI, the npx omnara commands, and the docs at docs.omnara.com.

One name warning, stated once: an Australian migration-authority product called the "OMARA Tool" (spelled O-M-A-R-A) occasionally surfaces near this keyword. It has nothing to do with Omnara the agent platform.

What Do You Need Before You Start?

You need an account, a terminal, and a model provider — in that order. The fastest path is Omnara Cloud: sign in at app.omnara.com and your first organization and project arrive pre-configured with a model provider called omnara-openrouter and a pool of Omnara-managed sandboxes called default-pool, so the quickstart config below runs as is. The CLI runs through npx and needs Node.js 22 or newer; the first command that needs your account opens the browser to sign you in automatically. For self-hosting you need Docker with Compose, plus a model key of your own (OpenAI, Anthropic, OpenRouter, Bedrock, LiteLLM, Ollama, or any compatible endpoint) because a fresh self-hosted instance ships with no models and no machines. Bringing your own keys and machines on Omnara Cloud costs nothing extra — the platform fee is $0.

How Do You Launch Your First Agent on Omnara Cloud?

Launching an agent takes four steps: sign in, write the config, launch it, and talk to it. This is the vendor's documented quickstart flow, verified against the current docs on 2026-11-02.

1. Sign in and let Omnara set up your defaults. Sign in at app.omnara.com. Your first sign-in creates your organization and project, plus omnara-openrouter (a model provider with frontier models such as anthropic/claude-fable-5.1 and openai/gpt-6.1-sol) and default-pool (a pool of Omnara-managed sandboxes with common development tools preinstalled).
2. Log the CLI in. Run npx omnara login — the browser sign-in opens automatically the first time — then npx omnara config select to pick your organization and project. Prefer the laziest path? Send your coding agent the prompt Help me set up Omnara by following https://www.omnara.com/SKILL.md and it walks the setup itself.
3. Save your agent config as agent.yaml. The example below is the vendor's own quickstart config (docs.omnara.com/quickstart, updated 2026-10-16): an engineering assistant that runs commands on a cloud machine, searches the web, and asks a question when a task is unclear.

   version: v1
instruction: |
  You are an engineering assistant. Use your machine to run
  commands. Use web search to find current information. Ask a
  question when a task is not clear.
model:
  provider_config: omnara-openrouter
  name: anthropic/claude-fable-5.1
tools:
  web_search: {}
  web_fetch: {}
  ask_question: {}
machine_sources:
  - machine_pool_name: default-pool

4. Launch it and give it a first message. Run npx omnara agents launch --file agent.yaml --name "Machine assistant" --message "Use your machine to report the operating system and the free disk space. Then find the latest stable Node.js release on the web and tell me the version." To reuse the config later, upload it as a named profile instead: npx omnara profiles create --name machine-assistant --file agent.yaml.
5. Follow the agent and send input. The event stream shows tool calls and the reply as it is generated; send a follow-up while it runs with npx omnara agents chat {agent-id}. To watch the conversation live in the browser, open https://app.omnara.com/projects/{project-id}/agents/{agent-id} — that dashboard URL is the heart of the "omnara ai agents dashboard" experience this guide's cluster targets.

The whole loop — sign in, one YAML file, one launch command — is why the keyword "how to use omnara" has a genuine beginner gap. If you came here looking for an omnara agent platform tutorial that strings the full loop together — config, launch, dashboard, approvals, and self-hosting — this guide is that page: the vendor docs describe each step, but no independent walkthrough covers what each piece actually does.

How Does agent.yaml Work?

An agent is defined by a YAML (or JSON) config, and the config docs call instruction "the single highest-leverage field you control" — the system prompt does more for agent quality than any other setting. Here is what each block of the config actually does, drawn from the vendor's configuration docs:

Two mechanics matter more than they look. First, changing a config creates a new config ID — a profile is the stable name that points at a config, so updating a profile moves future launches to the new config while already-running agents keep theirs. Second, the docs' trimmed example shows tools carrying their own permission block, like run_command with mode: always_ask so a human approves every command — the approval model is configured here, not bolted on later.

How Do You Watch and Steer an Agent from the Dashboard?

You steer an agent by opening its page in the dashboard and treating the event stream as a live feed: https://app.omnara.com/projects/{project-id}/agents/{agent-id}. Every tool call appears as it happens, the agent's reply streams in, and you can send a follow-up message while the agent is still working — the same conversation you would have in the terminal with npx omnara agents chat {agent-id}, but visible and clickable. When the agent needs a decision it cannot make alone, the dashboard surfaces the approval interaction there; you approve or deny, and the agent's turn continues or stops accordingly.

This is the modern form of the old mission-control idea: instead of mirroring one terminal session, the dashboard is the shared surface for your whole agent fleet. Your app, the CLI, and the dashboard all use the same REST API underneath, so a message you send from the dashboard is indistinguishable from one sent by code.

How Do Approvals and Permissions Keep Agents Safe?

Every tool on Omnara carries one of three permission modes, and the platform enforces the setting: always_allow runs the call immediately, always_ask pauses the call and opens a permission interaction that a human must answer, and always_deny refuses the call and tells the model. While a call waits in always_ask, the agent's turn simply waits — it cannot proceed until someone approves or denies. Permissions are set per tool in agent.yaml, and an MCP server can even carry a server-wide default with per-tool overrides, for example allowing a read tool while denying a delete tool on the same server.

Know the defaults before you trust them. An independent deep-dive of the permissions docs (Anubhav Bhatt, October 28, 2026) reports the defaults as always_allow for built-in tools, always_ask for MCP tools, and always_allow for custom tools — which means an agent with shell access and no explicit rules can run commands without asking. The same write-up's advice is worth repeating verbatim in spirit: set run_command to always_ask, or run the agent on a sandbox you can discard. The docs say nothing about approval timeouts, so verify what happens when nobody answers before you rely on a timeout that may not exist. For the general discipline of gating risky agent actions, this withHuman beginner guide covers the dedicated human-approval-layer approach in depth.

Where Do Omnara Agents Actually Run?

Agents run on machines — and a machine is anything running Omnara's small omnarad daemon, which connects outbound to Omnara so no inbound ports or SSH keys are ever needed. Install the daemon on a macOS or Linux laptop, a VM, or a container, and your agents can run commands and edit files there. Alternatively, use sandboxes from twelve providers the project names: Agent37, Arker, Blaxel, boxd, CreateOS, Daytona, E2B, Freestyle, Modal, Superserve, Tenki, and Unikraft. An agent can use several machines at once — a set of GPU servers, for example — and move between them.

The elegant part is the handoff the vendor describes: if your laptop goes offline, the agent can continue in a sandbox and sync its work back with git when the laptop returns. Durable state makes this possible — every step of every agent is saved to Postgres, so any worker can pick an agent back up after a crash, restart, or machine disconnect. The founder's design note, quoted in the October 28 deep-dive, is that many harnesses keep a JSONL or SQLite log inside one long-lived process, while Omnara stores inputs, model outputs, and tool calls as typed rows in Postgres; the founder claims one worker can therefore handle thousands of agents, since waiting agents hold no worker — the project's own claim, with no published benchmark.

How Do You Self-Host Omnara with Docker?

Self-hosting is the same product with your database: the API, CLI, SDK, and config format are identical on Omnara Cloud and self-hosted deployments. The vendor's local path needs only Docker with Compose:

1. Clone and start. Run git clone https://github.com/omnara-ai/omnara.git, then cd omnara and docker compose -f compose.yaml --profile app up -d. To build from source instead of the published images, add --build.
2. Open the console and sign up. Go to http://localhost:8000. The local email driver is console, so your verification link prints in docker compose logs api — no email provider needed.
3. Add a model provider, a model, and a machine. A new instance has no models or machines yet. In the console, add a model provider and a model, connect your computer under Machines, and share both with your project. Sandboxes also work once your instance has a public URL.
4. Point the CLI at your instance. Run npx omnara config --api-url http://localhost:8000/api/v1 --issuer-url http://localhost:8000 and then npx omnara login.
5. Adapt agent.yaml and launch. Use your provider and model names, and replace the machine_pool_name entry with machine_name: <your machine>. Launch with the same npx omnara agents launch --file agent.yaml command as the Cloud flow.

Two warnings, both from the vendor. First: the local defaults are intentionally insecure — for a real deployment, follow the self-hosting guide and the configuration reference. Second: production self-hosting needs Postgres, Redis, an S3-compatible bucket, a shared memory filesystem, and a public URL in front of everything (the October 28 deep-dive walks the deployment doc's checklist: run the migrate job first, mount the memory filesystem into every service, set the public URL, put a reverse proxy in front, and back up the memory directory with Postgres). The payoff for operating all that is data ownership: every agent's history lives in your own Postgres, queryable for analytics, evals, and training datasets. If container workflows are new to you, this Docker beginner guide covers the Compose fundamentals first.

How Do You Connect Claude Code, Slack, and GitHub to Omnara?

You connect your existing tools to Omnara in two directions: coding agents reach Omnara through its MCP server, and Omnara reaches your team through chat and GitHub integrations. The MCP server lives at https://app.omnara.com/mcp — it is listed in the official MCP Registry as com.omnara/omnara and in Claude's connectors directory. Connect Claude Code with claude mcp add --transport http omnara https://app.omnara.com/mcp and sign in with /mcp; connect Codex with codex mcp add omnara --url https://app.omnara.com/mcp and codex mcp login omnara. Sign-in happens in the browser, so there are no tokens to paste. This is the current answer to "omnara claude code sync": not a mirrored terminal session like the old product, but a proper MCP integration where your coding agent can launch and manage Omnara agents directly.

The integrations go the other way too. Mention the bot in Slack or Discord to start an agent in a thread, where it replies, asks questions, and requests approvals. On GitHub, an agent can start when a pull request opens or someone mentions it — then it reads the diff, comments, and submits reviews. The repository even ships a ready-made Slack coding agent and a PR review agent in its examples/ folder, each deployable with one prompt to your coding agent. If you have not wired GitHub automation before, this GitHub beginner guide covers the repository and pull-request basics first.

How Much Does Omnara Cost?

Self-hosting costs nothing for the software itself — Apache 2.0, run it on your own infrastructure. On Omnara Cloud there is no platform fee at all: you can bring your own model keys and machines for free, or pay as you go for Omnara's models at provider token rates and Omnara's sandboxes by active time and retained storage. See the pricing page for the current numbers; the structure below is the vendor's own comparison, restated as published on 2026-11-02:

One independent check is worth noting: the October 28 deep-dive found one row of Omnara's homepage comparison out of date against Anthropic's docs — Claude Managed Agents can run its sandbox on infrastructure you control, so the real difference is where the harness and control plane live, not whether self-hosted sandboxes exist. The author's conclusion stands: choose Omnara if you want to pick your models and machines, run the platform yourself, or keep agent data in your own database; choose a managed platform if you use one company's models and want that company to run everything.

Where Does Omnara Fit Among Agent Tools?

Omnara does not compete with the terminal agent you already use — the project's own docs draw the boundary lines clearly. Here is the "where Omnara fits" table from the repository, restated:

The n8n row deserves one line: n8n is a workflow builder for predictable automations, and Omnara names it as a different tool class — they solve different problems, never rivals. The cost angle deserves one too: agents burn tokens while they work, and a cost-proxy layer that watches spend is a natural companion to a platform like this — this Navige beginner guide covers watching and capping agent spend. Sibling lines drawn once, per the queue's lane discipline: 1046 MAO owns the multi-agent-canvas UI lane (a canvas is a different function from a mission-control dashboard), and 1065 withHuman owns the open approval-protocol lane (a protocol plus coding-agent hooks is a different layer from a managed platform) — different products, never rivals.

What Can You Build with Omnara?

The repository's examples/ folder ships ready-made agents, each one an agent.yaml plus a SKILL.md, deployable with one prompt to your coding agent. A selection, as published:

Cron triggers with time zones extend the pattern: message an existing agent on a schedule, launch a new one from a profile, or start a new Slack or Discord thread automatically.

7 Beginner Mistakes to Avoid with Omnara

Every mistake below is a real trap in the current product, compiled from the vendor docs and the independent deep-dive:

Sources

Every fact in this guide was fetched fresh on 2026-11-02 from one of these sources:

• omnara-ai/omnara GitHub repository README (github.com/omnara-ai/omnara) — product definition, quickstart, architecture, features, pricing, comparison tables, examples, MCP and CLI details
• omnara-ai/omnara GitHub repository metadata (api.github.com) — created 2025-07-09, 3,343 stars, 259 forks, Apache 2.0 license, updated 2026-11-02
• docs.omnara.com/quickstart (updated 2026-10-16) — Omnara Cloud quickstart: defaults, login, agent.yaml, launch and chat commands, dashboard URL pattern, setup skill
• PyPI omnara package metadata (pypi.org/pypi/omnara/json) — deprecation notice and current CLI installer path
• Anubhav Bhatt, "Omnara: An Open-Source Alternative to Claude Managed Agents," Medium, 2026-10-28 — independent explainer: earlier product, Show HN launch facts, Y Combinator backing, approval defaults, self-hosting requirements, comparison check against Anthropic's docs
• toolify.ai/tool/omnara (directory profile, updated 2026-10-08) — earlier-product description and stale install instructions, noted as outdated

Frequently Asked Questions

Is Omnara free?

Self-hosting is free — the code is Apache 2.0 and runs on your own infrastructure. Omnara Cloud charges no platform fee: bring your own model keys and machines and you pay nothing to Omnara, or pay as you go for their models at provider token rates and their sandboxes by active time and retained storage. The one cost you always pay is the model tokens your agents consume, to whichever provider you use.

What happened to pip install omnara?

The PyPI package is now a deprecated redirect. It belonged to the earlier product — a phone app for remote-controlling Claude Code and Codex sessions — which the team replaced with the current cloud agent platform. Install the current CLI with curl -fsSL https://omnara.com/install.sh | bash, or run it with zero install via npx omnara. Treat any tutorial recommending pip install omnara as stale.

Which models work with Omnara?

Any model behind an OpenAI Responses, OpenAI Chat Completions, or Anthropic Messages compatible endpoint. The docs name OpenAI, Anthropic, OpenRouter, Amazon Bedrock, LiteLLM, and Ollama, plus any endpoint you host yourself — including models behind LiteLLM-compatible gateways. On Omnara Cloud, the default omnara-openrouter provider ships with frontier models such as anthropic/claude-fable-5.1 and openai/gpt-6.1-sol.

Do I need to self-host Omnara?

No. Omnara Cloud gives you an organization, a project, a model provider, and a sandbox pool on first sign-in, and the API, CLI, SDK, and config format are identical on both. Self-host when you want the data: on your own deployment, every agent's history lives in your own Postgres, where you can query it for analytics, evals, and training datasets.

How is Omnara different from Claude Managed Agents?

Omnara is open source (Apache 2.0) and works with any compatible model on any infrastructure, including your own; Claude Managed Agents is a closed Anthropic service built around Claude. Omnara's own comparison table makes the case, and an independent October 2026 deep-dive checked it against Anthropic's docs and found one row out of date — Claude Managed Agents can use self-hosted sandboxes too, so the real difference is where the harness and control plane live. Choose Omnara to pick your models and machines or keep data in your own database; choose the managed service if you use one company's models and want that company to run everything.