omnara README

项目的 README,来自 github.com/omnara-ai/omnara。合并为一个 markdown 文件:README.md。

Omnara Omnara

The open-source managed agent platform

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

License: Apache 2.0 npm: @omnara/sdk Discord

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.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.

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: <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.

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<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

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

Features

Build agents

Run them anywhere

Connect them

Control them

Omnara vs Claude Managed Agents and OpenAI's Agents API

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.

Where Omnara fits

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

Examples

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.

Use Omnara from your coding agent

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.

FAQ

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.

Development

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.

Community

Discord · GitHub Issues · X · Security

License

Apache License 2.0

omnara (omnara-ai/omnara)

正在搜索数据库…

3.4K ·GitHub
这是什么?Omnara 是一个开源的托管式智能体平台,可通过 API 运行 AI 智能体,并内置工具、密钥、权限和流式输出功能。它是 Claude Managed Agents 和 OpenAI Agents API 的可自托管替代方案。
这是托管服务、我自己部署,还是两者都有?两者都有:你可以登录托管的 Omnara Cloud,也可以使用 Docker Compose 免费自托管整个平台,遵循 Apache 2.0 协议。底层是用于运行大量智能体的基础设施(包括 API、Postgres、无状态工作进程和机器),而不是单一的智能体运行框架。
怎样让智能体跑起来?在 Omnara Cloud 上,访问 app.omnara.com 登录,将配置写入 agent.yaml,然后用 CLI(npx omnara agents chat)或 TypeScript SDK/REST API 启动。自托管则需要 Docker 和 Compose,之后在控制台中添加模型服务商并连接机器,再使用同样的 CLI 流程。
使用前需要准备什么?CLI 和快速入门需要 Node.js 22 或更高版本;如果直接使用 SDK 或 REST API,需要从控制台获取 API 密钥;还需要你自己的模型服务商密钥(OpenAI、Anthropic、OpenRouter、Amazon Bedrock、LiteLLM 或 Ollama)。自托管还额外需要 Docker 和 Compose。
自托管时有哪些需要注意的地方?新的自托管实例启动时没有配置任何模型或机器,而且本地 Docker Compose 的默认设置刻意不够安全,因此正式部署需要参阅单独的自托管指南和配置参考文档。
多个团队能共用一套部署吗?可以,它支持多租户:单个部署可以同时服务多个组织,每个组织都有各自的成员、项目、密钥、模型服务商和机器。
如果智能体工作时我的笔记本断网了,会怎样?每一步都会保存到 Postgres 中,因此智能体在崩溃、重启或断开连接后可以从中断处继续。它甚至可以在沙箱中继续工作,并通过 git 把成果同步回来。
哪些模型可以在 Omnara 中使用?任何兼容 OpenAI Responses、OpenAI Chat Completions 或 Anthropic Messages 接口的模型都可以,包括 OpenAI、Anthropic、OpenRouter、Amazon Bedrock、LiteLLM 和 Ollama。
Omnara 和 Claude Managed Agents 或 OpenAI Agents API 有什么不同?后两者是封闭的、单一厂商的托管服务,只能使用某家公司的模型。Omnara 是开源的(Apache 2.0 协议),支持任意模型,可在任何地方运行,并且自托管用户可以把完整的智能体历史记录保存在自己的 Postgres 中。
我能在 Claude Code 或 Codex 中使用 Omnara 吗?可以,通过它的 MCP 服务器即可。连接任意支持 OAuth 的 MCP 客户端,然后在浏览器中登录(无需粘贴任何令牌),再在 Claude Code 中运行 /mcp,或在 Codex 中运行 'codex mcp login omnara',即可启动和管理智能体。
作者
omnara-ai
大小
114 MB
星标
3.4K
时长
1年
提交 · 90 天