Omnara: Estrutura de Agentes Durável de Código Aberto com Registro de Eventos Postgres

Omnara é uma API open-source para executar agentes de IA duráveis. Você cria um agente com uma chamada de API, e o Omnara executa o loop do agente, fornece sandboxes para execução de comandos e gerencia segredos, permissões e RBAC. É uma alternativa auto-hospedável aos Claude Managed Agents e à Agents API da OpenAI.

Arquitetura: Log de Eventos no Postgres + Workers Sem Estado

A maioria dos harnesses (Claude Code, Codex, OpenCode, Pi, Goose) mantém o loop do agente em um único processo de longa duração com um log JSONL ou SQLite. O Omnara, em vez disso, armazena cada entrada, saída do modelo e chamada de ferramenta como linhas tipadas em um log de eventos append-only no Postgres.

O loop é executado em workers sem estado no plano de controle. Cada worker executa uma iteração — uma chamada ao modelo ou suas chamadas de ferramentas —, então libera o agente e enfileira a próxima iteração via Postgres. Qualquer worker livre a pega, então as iterações podem rodar em máquinas diferentes. Cada iteração é confirmada em uma transação; se um worker morre no meio da iteração, nada é confirmado, seu lease expira e outro worker tenta novamente. Agentes esperando por um usuário, ferramenta ou nova tentativa não ocupam um worker, então um único worker pode multiplexar milhares de agentes.

Máquinas e o Daemon omnarad

Os workers que executam o loop do agente não são onde os comandos são executados. Qualquer máquina macOS ou Linux pode rodar um pequeno daemon (omnarad) que se conecta de saída ao Omnara — sem necessidade de portas de entrada. O agente então recebe ferramentas para essa máquina, como executar comandos ou editar arquivos. Um agente pode ter várias máquinas conectadas; por exemplo, um laptop e um sandbox na nuvem. Quando o laptop fica offline, o agente pode puxar as últimas alterações para o sandbox e continuar lá.

Início Rápido (Omnara Cloud)

Faça login em app.omnara.com. Seu primeiro projeto inclui um provedor de modelo (omnara-openrouter) e um pool de sandbox gerenciado (default-pool). Salve isto como 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

Inicie com a 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."

Converse com npx omnara agents chat <agent-id>, ou abra o dashboard para ver as chamadas de ferramentas e responder.

Auto-Hospedagem

Requer Docker com Compose:

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

Abra http://localhost:8000 e cadastre-se. O desenvolvimento local imprime o link de verificação em docker compose logs api, então não é necessário um provedor de e-mail. Uma nova instância não tem modelos ou máquinas; adicione um provedor de modelo e um modelo no console, conecte este computador em Machines e compartilhe ambos com seu projeto. Aponte a CLI para sua instância:

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

Em agent.yaml, use seus nomes de provedor e modelo e substitua machine_pool_name por machine_name: <your machine>.

SDK TypeScript

Crie uma chave de API no dashboard, exporte-a como OMNARA_TOKEN, instale com npm install @omnara/sdk, então:

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

Todo o código-fonte tem licença Apache 2.0 e pode ser auto-hospedado em uma única máquina via Docker Compose. É voltado para desenvolvedores que querem a ergonomia de agentes gerenciados sem entregar estado e modelos a um provedor hospedado.