Omnara: Open-Source-Harness für dauerhafte Agenten mit Postgres-Ereignisprotokoll

Omnara ist eine Open-Source-API zum Ausführen dauerhafter KI-Agenten. Sie erstellen einen Agenten per API-Aufruf, und Omnara übernimmt die Agentenschleife, stellt Sandboxes für die Befehlsausführung bereit und verwaltet Secrets, Berechtigungen und RBAC. Es ist eine selbst hostbare Alternative zu Claude Managed Agents und der Agents API von OpenAI.

Architektur: Postgres-Event-Log + zustandslose Worker

Die meisten Harnesses (Claude Code, Codex, OpenCode, Pi, Goose) halten die Agentenschleife in einem langlebigen Prozess mit einem JSONL- oder SQLite-Log. Omnara hingegen speichert jede Eingabe, Modellausgabe und jeden Tool-Aufruf als typisierte Zeilen in einem append-only Postgres-Event-Log.

Die Schleife läuft auf zustandslosen Workern in der Control Plane. Jeder Worker führt eine Iteration aus – einen Modellaufruf oder dessen Tool-Aufrufe –, gibt dann den Agenten frei und reiht die nächste Iteration über Postgres in die Warteschlange ein. Jeder freie Worker greift sie auf, sodass Iterationen auf verschiedenen Maschinen laufen können. Jede Iteration wird in einer Transaktion festgeschrieben; stirbt ein Worker mitten in der Iteration, wird nichts festgeschrieben, sein Lease läuft ab und ein anderer Worker versucht es erneut. Agenten, die auf einen Benutzer, ein Tool oder einen Retry warten, belegen keinen Worker, sodass ein einzelner Worker Tausende von Agenten multiplexen kann.

Maschinen und der omnarad-Daemon

Die Worker, die die Agentenschleife ausführen, sind nicht der Ort, an dem Befehle ausgeführt werden. Jede macOS- oder Linux-Maschine kann einen kleinen Daemon (omnarad) ausführen, der ausgehend eine Verbindung zu Omnara herstellt – eingehende Ports sind nicht erforderlich. Der Agent erhält dann Tools für diese Maschine, etwa zum Ausführen von Befehlen oder Bearbeiten von Dateien. Ein Agent kann mehrere Maschinen angehängt haben, z. B. einen Laptop und eine Cloud-Sandbox. Wenn der Laptop offline geht, kann der Agent die neuesten Änderungen in die Sandbox ziehen und dort fortfahren.

Schnellstart (Omnara Cloud)

Melden Sie sich bei app.omnara.com an. Ihr erstes Projekt enthält einen Modellanbieter (omnara-openrouter) und einen verwalteten Sandbox-Pool (default-pool). Speichern Sie dies als 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

Starten Sie mit der 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."

Chatten Sie mit npx omnara agents chat <agent-id> oder öffnen Sie das Dashboard, um Tool-Aufrufe zu beobachten und zu antworten.

Selbsthosting

Erfordert Docker mit Compose:

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

Öffnen Sie http://localhost:8000 und registrieren Sie sich. Bei der lokalen Entwicklung wird der Bestätigungslink in docker compose logs api ausgegeben, sodass kein E-Mail-Anbieter benötigt wird. Eine neue Instanz hat keine Modelle oder Maschinen; fügen Sie einen Modellanbieter und ein Modell in der Konsole hinzu, verbinden Sie diesen Computer unter Machines und geben Sie beides für Ihr Projekt frei. Richten Sie die CLI auf Ihre Instanz aus:

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

Verwenden Sie in agent.yaml Ihre Anbieter- und Modellnamen und ersetzen Sie machine_pool_name durch machine_name: <your machine>.

TypeScript-SDK

Erstellen Sie einen API-Schlüssel im Dashboard, exportieren Sie ihn als OMNARA_TOKEN, installieren Sie mit npm install @omnara/sdk und dann:

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

Der vollständige Codebestand ist unter Apache 2.0 lizenziert und kann auf einer einzigen Maschine über Docker Compose selbst gehostet werden. Er richtet sich an Entwickler, die die Ergonomie verwalteter Agenten wünschen, ohne Zustand und Modelle einem Hosting-Anbieter zu überlassen.