# Omnara: a self-hostable runtime for managed coding agents

> Omnara is an Apache-2.0 Go platform that keeps agent state in Postgres and lets you swap models, sandboxes and tools. It is aimed at teams who want managed-agent execution without handing the whole loop to a vendor.

**omnara-ai/omnara** — The open-source alternative to Claude Managed Agents

- Repository: https://github.com/omnara-ai/omnara
- Website: https://www.omnara.com
- Stars: 2,879 · Forks: 231
- Language: Go
- License: Apache-2.0
- Published: 2026-09-24 · Updated: 2026-09-24 · Language: en
- Canonical page: https://hysenlabs.com/projects/omnara-ai-omnara

## The gap Omnara fills between an agent framework and a hosted agent product

Most agent code starts as a loop in a script. The model call, the tool dispatch and the conversation history all live in the same process, and when that process dies the run is gone. Omnara's README frames the project as "The API for production-grade agents" and positions it as the open source alternative to Claude Managed Agents. What it actually supplies is the part that is tedious to write: durable execution, state persistence, a machine abstraction, and an access-control layer, exposed through a REST API defined in api/openapi/openapi.yaml and served under /api/v1.

The intended users are named explicitly. Developers building agents for internal use or customer-facing products keep control of who can use each agent, what input it receives and how output reaches users, while Omnara handles execution and state in between. Teams get a dashboard and a first-party Slack connector instead of an API client. Those are different products sharing one backend, and the repository reflects that: there is a frontend/ directory built from a React app, and a Go service tree under cmd/ and internal/.

The claim worth scrutinising is durability. The README states that agent state is committed atomically to Postgres and that agents recover automatically from crashes, restarts and temporary machine disconnects. That is a design statement, not a benchmark, and the repository does not publish recovery-time numbers. What you can verify from the layout is that Postgres is a first-class dependency: compose.yaml runs postgres:18-alpine, and migrations/ plus sqlc.yaml indicate generated database code rather than ad-hoc SQL.

## How Omnara separates the API process, the worker and the maintenance loop

The architecture is visible in the build and environment files rather than in prose. The Dockerfile defines separate build stages for omnara-api, omnara-worker and a maintenance binary, each compiled from a different entry point under cmd/. They are distinct processes with distinct metrics ports: OMNARA_API_METRICS_ADDR defaults to :8081, OMNARA_WORKER_METRICS_ADDR to :8082 and OMNARA_MAINTENANCE_METRICS_ADDR to :8083, while the main API listens on OMNARA_API_ADDR, default :8080.

Redis, or rather Valkey in the compose file, is not just a cache. The .env.example describes Redis Pub/Sub wakeups as best-effort and defines OMNARA_DAEMON_SOCKET_FALLBACK_DRAIN_INTERVAL with a 30s default plus 10s of jitter, an API-side fallback for connected daemon sockets when wakeups are missed. That tells you the delivery path to a running agent is a push notification with a polling safety net, and that the authors expect missed wakeups to be normal rather than exceptional.

Worker capacity is bounded and configurable. OMNARA_WORKER_CAPACITY defaults to 4, with separate pools for asynchronous tools (OMNARA_WORKER_ASYNC_TOOL_CAPACITY, 32) and background tools (OMNARA_WORKER_BACKGROUND_TOOL_CAPACITY, 8). If you are sizing a deployment, those three numbers, not the API replica count, determine how many agent steps proceed in parallel. Nothing in the README explains how to tune them, which is a real gap for anyone planning capacity.

Agent definitions themselves are YAML profiles. The README's example sets an instruction block and a model with provider_config: omnara-openrouter and name: openai/gpt-5.6-sol. The profile is uploaded once and then launched, which means the same definition can be reused across runs and, presumably, diffed in version control.

## Installing Omnara with Docker Compose and launching a first agent

Self-hosting requires Docker with Compose. The README gives two paths: pull published images, or build from source. The published-image path clones the repository and starts the app profile, which brings up the API, worker, Postgres, Valkey and MinIO.

```bash
git clone https://github.com/omnara-ai/omnara.git
cd omnara
docker compose -f compose.yaml --profile app up -d
```

After that, open http://localhost:8000. The README notes that the local authentication email is written to `docker compose logs api`, so you can finish signup without configuring an email provider. If you prefer to build the binaries yourself, the alternative command is `docker compose --profile app up -d --build`, which uses the multi-stage Dockerfile and compiles the Go services and the React frontend locally.

Once you are signed in, the documented flow is to add a model provider credential in the console, create an agent profile, and launch it. The CLI path uses npx. You log in, then create a profile from a YAML file.

```bash
npx omnara login
npx omnara profiles create --name agent --file agent.yaml
```

The README shows the command returning an id beginning with aprf_, which is the profile identifier you pass when launching. A minimal agent.yaml looks like this, taken from the README's getting-started example.

```yaml
instruction: |
  You are a coding agent running gpt-5.6-sol. Use the tools
  you have available to solve coding problems for the user.
model:
  provider_config: omnara-openrouter
  name: openai/gpt-5.6-sol
```

Launching takes the profile id and the same file, then prints a console URL you open in a browser.

```bash
npx omnara agents launch --profile $AGENT_PROFILE_ID --file agent.yaml
```

The README's example then opens https://app.omnara.com/projects/[$PROJECT_ID]/agents/[$AGENT_ID], which is the cloud console. On a self-hosted instance your equivalent URL is on your own OMNARA_PUBLIC_URL, which defaults to http://localhost:8000 in the compose stack.

## Where Omnara is the wrong tool, and the sharp edges in the defaults

The most important limitation is stated by the project itself: local development uses intentionally insecure defaults, and the README says not to use those in a deployed environment. The compose file sets OMNARA_ALLOW_INSECURE_DEV_DEFAULTS to 1 by default, ships Postgres with the password omnara, and runs MinIO with root credentials omnara and omnara-blobs. The secret encryption keys, OMNARA_SECRET_ENCRYPTION_KEYS and OMNARA_SECRET_ENCRYPTION_ACTIVE_KEY_ID, default to empty in the compose environment block. If you bring the stack up and expose port 8000 without changing those, you have a working demo and an open door.

Omnara is also the wrong choice if you do not want to operate Postgres and Redis. The durable-state guarantee is a Postgres guarantee. There is no documented SQLite mode for the server, even though modernc.org/sqlite appears in go.mod. Anyone wanting a single binary with no external database should read that dependency as a test or tooling detail, not a deployment option.

A second boundary is model compatibility. Omnara supports OpenAI Responses, OpenAI Chat Completions and Anthropic Messages, and the README says more API formats are coming. If your workflow depends on a provider-specific feature outside those three shapes, the abstraction will get in the way rather than help. The same applies to sandboxes: Blaxel, Daytona, Modal and Unikraft are listed, plus your own laptop or VM, with "more coming soon" as the qualifier.

Finally, the documentation is uneven. The README covers the happy path well and links to a self-hosting guide and a configuration reference, but it does not document rollback, backup or restore, or how to drain an in-flight agent before a worker restart. Those are the questions that decide whether a durable-agent platform survives its first production incident, and they are not answered in the repository files.

## Omnara compared with building directly on a model provider SDK

The obvious alternative is to skip the platform and write the loop yourself against a provider SDK, keeping your own database table for run state. The difference is where the hard parts live. In that approach you own checkpointing, retry semantics, the mapping from a crashed process back to a resumable run, and the access-control model that decides which user can invoke which agent. Omnara takes those on and hands you a REST API plus a YAML profile format in exchange.

The trade is real in both directions. A hand-rolled loop can be simpler than a five-service Compose stack for a single internal agent that runs for thirty seconds and never needs to resume. The moment you need a run to survive a deploy, or you want a non-engineer to start an agent from Slack, the hand-rolled version starts accumulating the same components Omnara already ships. The honest dividing line is whether you want to own a Postgres schema for agent state. If you do, and you enjoy that, you probably do not need this. If you do not, Omnara's migrations directory is the thing you are buying.

A narrower alternative is to use only the cloud product and skip self-hosting. The README presents both: Omnara Cloud at app.omnara.com, or run it yourself under Apache 2.0. The self-hosted path adds a specific capability the cloud path describes separately: queryable state, where self-hosted deployments can query agent history directly in Postgres for analytics, evals, prompt analysis and training datasets. If that direct SQL access is the reason you are interested, self-hosting is not optional.

## Maintenance, releases and what Apache 2.0 means here

The repository is not archived, and the last push was on 2026-09-20, four days before this writing. Recent tags show a steady cadence: omnarad v0.1.24 and cluster v0.1.30 both landed on 2026-09-17, with an omnarad stable channel published on 2026-08-05. The naming suggests two separately versioned artifacts, a daemon and a cluster component, which means an upgrade is not necessarily a single version bump across the whole deployment.

That is the practical upgrade cost. Because the API, worker and maintenance processes are built from the same module and share the same database, a version skew between them is the failure mode to guard against. The .env.example comment on OMNARA_PUBLIC_API_URL is explicit that it must be set identically on API, worker and maintenance. Treat the three binaries as one deployable unit even though they scale separately.

Development requirements are worth noting for anyone who wants to patch rather than consume: the go.mod declares Go 1.27.1, and the README asks for Node.js 24 or newer with Corepack plus Docker with Compose. The repository gate is `make verify`, with `make test-integration` and `make test-service-e2e` for deeper runs. Provider-backed live tests exist behind `make test-live-*` targets, require the corresponding credentials, and run in CI on every push to main; on a pull request you add the live-tests label to trigger them.

On licensing, Apache 2.0 covers the code in this repository and permits commercial use and modification. It does not automatically cover the hosted service, the model providers you connect, or the sandbox vendors named in the README, each of which has its own terms and its own bill. If you self-host, your cost is infrastructure and operator time; there is no pricing information in the repository, and the README does not discuss it.

## Conclusion

Adopt Omnara if you want the execution and state layer of a managed-agent product to run on your own Docker host, with Postgres holding the durable record and model or sandbox choices left to you. Do not adopt it if you need a fully managed service with no operational surface, or if your agent logic is already tightly bound to one provider's SDK. Before committing, verify three things: that the insecure development defaults in compose.yaml are replaced per the self-hosting guide, that OMNARA_SECRET_ENCRYPTION_KEYS is set so stored provider credentials are encrypted with a key you control, and that the model provider you intend to use is reachable through one of the supported API formats.

## FAQ

### What is Omnara?

Omnara is an open source platform for running managed agents, described in its README as the API for production-grade agents and as the open source alternative to Claude Managed Agents. It handles execution and state while you choose the models, tools, machines and how users interact with each agent.

### Is Omnara free?

The code is released under the Apache License 2.0, and the README offers both Omnara Cloud and a self-hosted deployment. The repository does not document pricing for the cloud service, so the only cost information available here is the licence and the infrastructure you run yourself.

### How do I install Omnara?

Self-hosting requires Docker with Compose. The README's published-image path is to clone the repository and run `docker compose -f compose.yaml --profile app up -d`, then open http://localhost:8000 and read the local authentication email from `docker compose logs api` to complete signup.

### Does Omnara run on Windows?

The README documents self-hosting through Docker with Compose and does not list a native Windows installation path. The go.mod includes github.com/Microsoft/go-winio, which indicates Windows-specific code exists in the tree, but the repository does not describe a supported Windows deployment.

### Which models and sandboxes can Omnara use?

The README lists OpenRouter, LiteLLM and Ollama as compatible endpoints and states that Omnara supports OpenAI Responses, OpenAI Chat Completions and Anthropic Messages. For machines, it names Blaxel, Daytona, Modal and Unikraft sandboxes, plus your own laptop or VM, and says more are coming.

### Can I query Omnara's agent history directly?

Yes, for self-hosted deployments. The README states that self-hosted deployments can query agent history directly in Postgres for analytics, evals, prompt analysis and training datasets, which is a capability it lists separately from the cloud offering.

## Sources

- [License: Apache-2.0](https://github.com/omnara-ai/omnara/blob/main/LICENSE)
- [omnara-ai/omnara on GitHub](https://github.com/omnara-ai/omnara)
- [Project website](https://www.omnara.com)
- [README](https://github.com/omnara-ai/omnara/blob/main/README.md)
- [Releases](https://github.com/omnara-ai/omnara/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/omnara-ai-omnara