项目的 README,来自 github.com/omnara-ai/omnara。合并为一个 markdown 文件:README.md。
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.
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.2
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 <agent-id>,
or open it in the dashboard to watch its tool calls and reply.
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
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: <your machine>. 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.
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<br/>REST API · TypeScript SDK"]
team["Your team<br/>CLI · dashboard<br/>Slack · Discord · GitHub"]
end
subgraph omnara["Omnara"]
api["API<br/>launch · input<br/>event stream · approvals"] <--> pg[("Postgres<br/>each agent's event log")] <--> worker["Workers<br/>run the agent loop"]
end
subgraph plug[" "]
models["Models<br/>OpenAI · Anthropic<br/>OpenRouter · self-hosted"]
tools["Tools<br/>built-in · skills<br/>MCP · custom"]
machines["Machines<br/>sandboxes or your own<br/>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
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.
api/openapi/openapi.yaml, a
TypeScript SDK (@omnara/sdk),
a CLI (omnara), and an MCP server.Claude Managed Agents and OpenAI's Agents API are proprietary hosted services that run one company's models on that company's cloud, with your agent history stored by the vendor. Omnara does the same job as an open-source platform you can run anywhere, with any model, and keep every agent's history in your own Postgres.
| Omnara | Claude Managed Agents | OpenAI's Agents API | |
|---|---|---|---|
| Source | Open source (Apache 2.0) | Closed | Open-source harness (Codex). The hosted service is OpenAI's. |
| Models | Any compatible model | Claude | OpenAI |
| Agent loop | Omnara's, works with any model | Anthropic's, built for Claude | Codex, run and updated by OpenAI |
| Where the platform runs | Omnara Cloud, or your own cloud account or data center | Anthropic's cloud | OpenAI's cloud |
| Where agents run | Sandboxes from many providers, or your own machines | Anthropic sandboxes, or your own sandboxes | OpenAI sandboxes, partner sandboxes, or your own machines |
| Operations | Your choice: we run it on Omnara Cloud, we deploy and manage it in your own cloud (BYOC) or on premises, or you self-host it. | Managed by Anthropic. You run the sandbox side if you self-host sandboxes. | Managed by OpenAI. You run the environment if you bring your own. |
| Agent history | Stored by Omnara on Omnara Cloud and queryable through the API. In your own Postgres when self-hosted. | Stored by Anthropic, readable and deletable through the API. Not currently eligible for Zero Data Retention or HIPAA BAA coverage. | Stored by OpenAI. No Zero Data Retention support. US data residency only. |
| Pricing | Free to self-host. On Omnara Cloud, free with your own keys and machines, or pay as you go for our models and sandboxes. | Claude token rates plus $0.08 per active session-hour | OpenAI model rates, plus standard rates for OpenAI tools and hosted sandboxes |
For production agents, choose Omnara. Of the three, it's the only one that's fully open source, runs any model, and can be self-hosted in full, and Omnara Cloud has no platform fee. A lab's service makes sense if you'll stay on that company's models and are fine with it holding your agents' history.
| If you use | It's good for | Omnara adds |
|---|---|---|
| Workflow builders, such as n8n or Zapier | Predictable, step-by-step automations | Open-ended agents that run code on machines and keep state for days |
| Agent frameworks, such as Mastra, LangChain, or the OpenAI Agents SDK | Agent logic in your app's code | Hosting, state, machines, permissions, and integrations, with agents created and changed through an API instead of a redeploy |
| Agent harnesses, such as Claude Code, the Claude Agent SDK, Codex, OpenCode, or Pi | One agent loop in a terminal or on one machine | Cloud agents that run as a service, across machines and users, started from your app, Slack, GitHub, or a schedule |
| Managed agent platforms, such as Claude Managed Agents or the Agents API | Hosted agents on one company's models | The same model of hosted agents, open source, on any model, and self-hostable |
Each of these is an agent.yaml plus a SKILL.md in examples/,
and you can deploy any of them with one prompt to your coding agent.
There are also code samples for a CLI chat app built on the TypeScript SDK, custom tools over webhooks, and a SharePoint filesystem mount.
MCP server. Connect Claude Code, Codex, Cursor, or any MCP client that
supports OAuth to https://app.omnara.com/mcp to launch and manage Omnara
agents. You sign in through the browser, so there are no tokens to paste. In
Claude, add it from the
connectors directory. Omnara is
also listed in the official MCP Registry as com.omnara/omnara.
claude mcp add --transport http omnara https://app.omnara.com/mcp
codex mcp add omnara --url https://app.omnara.com/mcp
Then sign in with /mcp in Claude Code or codex mcp login omnara in Codex.
See Connecting MCP clients.
CLI. omnara manages agents,
profiles, machines, model providers, secrets, skills, and cron triggers from
your terminal or your coding agent's shell. Run npx omnara --help to start.
Setup skill. skills/setup-omnara-agent,
also served at omnara.com/SKILL.md, walks a
coding agent through setting up Omnara for your project.
Docs for LLMs. docs.omnara.com/llms.txt.
What is Omnara? The open-source managed agent platform for running AI agents in production on any model and any machine, hosted on Omnara Cloud or self-hosted.
How is Omnara different from Claude Managed Agents and OpenAI's Agents API? Those are proprietary services that run one company's models and store your agents' history on that company's cloud. Omnara is open source under Apache 2.0, works with any model on your own keys, runs on any machine, and can be self-hosted in full, so the agent loop and its history stay on your infrastructure.
How much does it cost? Nothing to self-host. Omnara Cloud has no platform fee. You can bring your own model keys and machines for free, or pay as you go for our models at provider token rates and our sandboxes by active time and retained storage. See pricing.
Can I self-host it? Yes. Run it with Docker Compose locally, then follow the self-hosting guide for production. Or we can deploy and manage it for you in your own cloud (BYOC) or on premises: book a call with the founders. The API, CLI, SDK, and config format are the same on Omnara Cloud and self-hosted deployments.
Which models work? Any model behind an OpenAI Responses, OpenAI Chat Completions, or Anthropic Messages compatible endpoint, including OpenAI, Anthropic, OpenRouter, Amazon Bedrock, LiteLLM, and Ollama.
Source development requires the Go version declared in go.mod,
Node.js 24 or newer with Corepack, ripgrep, and Docker with Compose. Run the
fast repository gate with make verify. See CONTRIBUTING.md
for the full test suite, generated-code workflows, and pull request
expectations.
Discord · GitHub Issues · X · Security