Omnara

The open-source managed agent platform

The open-source, self-hostable alternative to Claude Managed Agents and OpenAI's Agents API.

Website · Quickstart · Docs · API · Changelog · Discord

Omnara is an open-source managed agent platform. Use the API to run AI agents on any model and any machine, with tools, secrets, permissions, and streaming built in. Self-host it for free under Apache 2.0, or use Omnara Cloud.

Quickstart

Omnara Cloud

Sign in at app.omnara.com. Your first project comes with a model provider (omnara-openrouter) and a pool of managed sandboxes (default-pool), so this config runs as is. Save it 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 it with the CLI (Node.js 22 or newer). If you're not logged in, the first command opens your browser to sign in.

npx omnara agents launch --file agent.yaml \

--name "Machine assistant" \ --message "Report this machine's operating system and free disk space."

Chat with the agent in your terminal with npx omnara agents chat , or open it in the dashboard to watch its tool calls and reply.

Launch it from your code with the TypeScript SDK

Create an API key in the dashboard and export it as OMNARA_TOKEN, install the SDK with npm install @omnara/sdk, and use the org and project IDs that npx omnara config prints:

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." }, })

const agentID = launched.data.agent.id for await (const event of openAgentEventStream({ client, path: { ...path, agentID } })) { console.log(event) }

The quickstart shows the same flow with the REST API.

To have your coding agent do the setup, give it this prompt:

Help me set up Omnara by following https://www.omnara.com/SKILL.md

Self-host

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. To build from source instead of using published images, run docker compose --profile app up -d --build.

A new instance has no models or machines yet. In the console, add a model provider and a model, connect this computer under Machines, and share both with your project. Sandboxes also work once your instance has a public URL.

Point the CLI at your instance and log in:

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 the machine_pool_name entry with machine_name: . Then launch it with the same command as above.

This Compose setup uses local development defaults, such as built-in encryption keys and email links printed to the logs. For production, set your own keys and follow the self-hosting guide and the configuration reference.

How it works

Your product talks to Omnara, and Omnara runs each agent with the model, tools, and machines in its config.

flowchart TB

subgraph yours["Your side"] users(["Your users"]) --> app["Your app REST API · TypeScript SDK"] team["Your team CLI · dashboard Slack · Discord · GitHub"] end subgraph omnara["Omnara"] api["API launch · input event stream · approvals"] <--> pg[("Postgres each agent's event log")] <--> worker["Workers run the agent loop"] end subgraph plug[" "] models["Models OpenAI · Anthropic OpenRouter · self-hosted"] tools["Tools built-in · skills MCP · custom"] machines["Machines sandboxes or your own laptop, VM, container"] end app --> api team --> api worker --> models worker --> tools worker --> machines

classDef side fill:none,stroke:#8b949e,stroke-width:1px classDef core fill:#506FCF,stroke:#3D5BB5,stroke-width:1px,color:#ffffff classDef store fill:#3D5BB5,stroke:#2E4794,stroke-width:1px,color:#ffffff classDef plugin fill:none,stroke:#85A0E6,stroke-width:1.5px class users,app,team side class api,worker core class pg store class models,tools,machines plugin style yours fill:none,stroke:#8b949e,stroke-dasharray:4 3 style omnara fill:#506FCF14,stroke:#506FCF,stroke-width:1.5px style plug fill:none,stroke:#85A0E6,stroke-dasharray:4 3 linkStyle default stroke:#8b949e,stroke-width:1.5px

• API. Your app, the CLI, and the dashboard all use the same REST API to launch agents, send messages, and answer approvals. Events stream back as they happen.
• Postgres. Every step of every agent is saved here. That record is the agent's state, so any worker can pick an agent back up after a crash or restart.
• Workers. Stateless processes that build the model context, call the model, and run tools. An agent only uses a worker while it's taking a turn, so one worker can serve many agents. Add workers to handle more turns at once.
• Machines. Each machine runs the omnarad daemon, which connects out to Omnara, so agents can run commands there without any inbound ports.

Omnara also uses Redis, blob storage for attachments and tool outputs, and a memory filesystem. The architecture docs cover the details.

Features

Build agents

• [Any model](https://docs.omnara.com/organization/model-providers). Bring your own keys for OpenAI, Anthropic, OpenRouter, Amazon Bedrock, LiteLLM, Ollama, or any compatible endpoint, including models you host yourself.
• [Tools](https://docs.omnara.com/tools/built-in). Built-in tools for shell commands, files, web search and fetch, and asking a person a question, plus MCP servers and custom tools that run in your own systems.
• [Skills](https://docs.omnara.com/tools/skills). Package instructions and files once, attach them to any agent, and the agent loads them when it needs them.
• [Memory](https://docs.omnara.com/agents/configuration#memory-stores). Memory stores give agents files that persist between conversations and can be shared with other agents, with read or read-write access per agent.
• [Subagents](https://docs.omnara.com/agents/configuration#subagents). An agent can start subagents with a fresh context, check their progress, and send them new instructions. Each subagent is a full agent you can inspect.

Run them anywhere

• [Machines](https://docs.omnara.com/machines/overview). Machines are tools the agent uses. Install the Omnara daemon on any macOS or Linux laptop, VM, or container and your agents can run commands and edit files there, with no inbound ports or SSH keys. Or use sandboxes from twelve providers (Agent37, Arker, Blaxel, boxd, CreateOS, Daytona, E2B, Freestyle, Modal, Superserve, Tenki, Unikraft). An agent can use several machines at once (for example, a set of GPU servers) and move between them. If your laptop goes offline, the agent can continue in a sandbox and sync its work back with git.
• [Durable state](https://docs.omnara.com/agents/failure-handling). Every step is saved, so agents pick up where they left off after crashes, restarts, and machine disconnects, and crash recovery doesn't rerun tools.
• [Live config changes](https://docs.omnara.com/events/sending-input#change-the-config-mid-conversation). Change a running agent's model, tools, permissions, or instructions through the API. The change applies at its next model call, without restarting the conversation or redeploying.
• [Schedules](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/create-cron-trigger). Cron triggers with time zones can message an existing agent, launch a new one from a profile, or start a new Slack or Discord thread.

Connect them

• [Slack, Discord, and GitHub](https://docs.omnara.com/integrations/overview). 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 read the diff, comment, and submit reviews. To connect another service, build a custom integration on the same public API.
• [Streaming](https://docs.omnara.com/events/streaming) and [webhooks](https://docs.omnara.com/events/webhooks). Stream every event as it happens or receive it as a webhook, and send new messages while the agent works.
• [Permissions](https://docs.omnara.com/tools/permissions). Each tool can run immediately, ask a person first, or be blocked. The platform enforces the setting, and the agent waits until someone approves or denies the call.
• [API, SDK, and CLI](https://docs.omnara.com/api/overview). A REST API defined in api/openapi/openapi.yaml, a TypeScript SDK (@omnara/sdk), a CLI (omnara), and an MCP server.

Control them

• [Role-based access control](https://docs.omnara.com/organization/members) and [secrets](https://docs.omnara.com/organization/secrets). Organization and project roles for users and API keys. Credentials for models, machines, and MCP servers are stored once and shared with each proje