Omnara: Open-Source Durable Agent Harness with Postgres Event Log

Omnara is an open-source API for running durable AI agents. You create an agent with an API call, and Omnara runs the agent loop, provides sandboxes for command execution, and handles secrets, permissions, and RBAC. It's a self-hostable alternative to Claude Managed Agents and OpenAI's Agents API.

Architecture: Postgres Event Log + Stateless Workers

Most harnesses (Claude Code, Codex, OpenCode, Pi, Goose) keep the agent loop in one long-lived process with a JSONL or SQLite log. Omnara instead stores every input, model output, and tool call as typed rows in an append-only Postgres event log.

The loop runs on stateless workers in the control plane. Each worker executes one iteration — a model call or its tool calls — then releases the agent and enqueues the next iteration via Postgres. Any free worker picks it up, so iterations can run on different machines. Each iteration commits in one transaction; if a worker dies mid-iteration, nothing commits, its lease expires, and another worker retries. Agents waiting on a user, tool, or retry hold no worker, so a single worker can multiplex thousands of agents.

Machines and the omnarad Daemon

The workers running the agent loop are not where commands execute. Any macOS or Linux machine can run a small daemon (omnarad) that connects outbound to Omnara — no inbound ports needed. The agent then gets tools for that machine, like running commands or editing files. An agent can have multiple machines attached; e.g., a laptop and a cloud sandbox. When the laptop goes offline, the agent can pull latest changes to the sandbox and continue there.

Quickstart (Omnara Cloud)

Sign in at app.omnara.com. Your first project includes a model provider (omnara-openrouter) and a managed sandbox pool (default-pool). Save this as agent.yaml:

version: v1
instruction: |
  You are an engineering assistant. Use your machine to run commands.
model:
  provider_config: omnara-openrouter
  name: anthropic/claude-fable-5.1
machine_sources:
  - machine_pool_name: default-pool

Launch with the CLI (Node.js 22+):

npx omnara agents launch --file agent.yaml \
  --name "Machine assistant" \
  --message "Report this machine's operating system and free disk space."

Chat with npx omnara agents chat <agent-id>, or open the dashboard to watch tool calls and reply.

Self-Hosting

Requires Docker with Compose:

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

Open http://localhost:8000 and sign up. Local development prints the verification link in docker compose logs api, so no email provider is needed. A new instance has no models or machines; add a model provider and model in the console, connect this computer under Machines, and share both with your project. Point the CLI at your instance:

npx omnara config --api-url http://localhost:8000/api/v1 --issuer-url http://localhost:8000
npx omnara login

In agent.yaml, use your provider and model names and replace machine_pool_name with machine_name: <your machine>.

TypeScript SDK

Create an API key in the dashboard, export it as OMNARA_TOKEN, install with npm install @omnara/sdk, then:

import { readFile } from 'node:fs/promises'
import { bearerToken, createOmnaraClient, openAgentEventStream, sdk } from '@omnara/sdk'

const client = createOmnaraClient({ auth: bearerToken(process.env.OMNARA_TOKEN!) })
const path = { orgID: 'org_...', projectID: 'proj_...' }
const config = await sdk.createAgentConfig({
  client, path,
  body: { source: await readFile('agent.yaml', 'utf8'), source_format: 'yaml' },
})
const launched = await sdk.createAgent({
  client, path,
  body: { config: config.data.id, message: "Report this machine's free disk space." },
})
for await (const event of openAgentEventStream({ client, path: { ...path, agentID: launched.data.agent.id } })) {
  console.log(event)
}

The full codebase is Apache 2.0 licensed and self-hostable on a single machine via Docker Compose. It's aimed at developers who want managed-agent ergonomics without handing state and models to a hosted provider.