Omnara: Postgres 이벤트 로그를 갖춘 오픈소스 내구성 에이전트 하네스

Omnara는 내구성 있는 AI 에이전트를 실행하기 위한 오픈소스 API입니다. API 호출로 에이전트를 생성하면 Omnara가 에이전트 루프를 실행하고, 명령 실행을 위한 샌드박스를 제공하며, 시크릿, 권한, RBAC를 처리합니다. Claude Managed Agents와 OpenAI의 Agents API에 대한 셀프 호스팅 대안입니다.

아키텍처: Postgres 이벤트 로그 + 상태 비저장 워커

대부분의 하네스(Claude Code, Codex, OpenCode, Pi, Goose)는 에이전트 루프를 JSONL 또는 SQLite 로그와 함께 하나의 장기 실행 프로세스에 유지합니다. 반면 Omnara는 모든 입력, 모델 출력, 도구 호출을 추가 전용 Postgres 이벤트 로그에 타입이 지정된 행으로 저장합니다.

루프는 컨트롤 플레인의 상태 비저장 워커에서 실행됩니다. 각 워커는 한 번의 반복(모델 호출 또는 해당 도구 호출)을 실행한 후 에이전트를 해제하고 Postgres를 통해 다음 반복을 큐에 넣습니다. 사용 가능한 워커가 이를 가져가므로 반복이 서로 다른 머신에서 실행될 수 있습니다. 각 반복은 하나의 트랜잭션으로 커밋되며, 워커가 반복 중간에 죽으면 아무것도 커밋되지 않고 임대가 만료되어 다른 워커가 재시도합니다. 사용자, 도구 또는 재시도를 기다리는 에이전트는 워커를 점유하지 않으므로 단일 워커가 수천 개의 에이전트를 멀티플렉싱할 수 있습니다.

머신과 omnarad 데몬

에이전트 루프를 실행하는 워커는 명령이 실행되는 곳이 아닙니다. 모든 macOS 또는 Linux 머신은 Omnara에 아웃바운드로 연결되는 작은 데몬(omnarad)을 실행할 수 있습니다. 인바운드 포트가 필요 없습니다. 그러면 에이전트는 해당 머신에 대한 도구(예: 명령 실행 또는 파일 편집)를 얻게 됩니다. 에이전트에는 여러 머신을 연결할 수 있습니다. 예를 들어 노트북과 클라우드 샌드박스가 있습니다. 노트북이 오프라인이 되면 에이전트는 최신 변경 사항을 샌드박스로 가져와서 계속 진행할 수 있습니다.

빠른 시작 (Omnara Cloud)

app.omnara.com에 로그인하세요. 첫 프로젝트에는 모델 제공자(omnara-openrouter)와 관리형 샌드박스 풀(default-pool)이 포함되어 있습니다. 다음을 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

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

npx omnara agents chat <agent-id>로 채팅하거나 대시보드를 열어 도구 호출을 보고 응답하세요.

셀프 호스팅

Compose가 포함된 Docker가 필요합니다:

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

http://localhost:8000을 열고 가입하세요. 로컬 개발 시 docker compose logs api에 인증 링크가 출력되므로 이메일 제공자가 필요 없습니다. 새 인스턴스에는 모델이나 머신이 없습니다. 콘솔에서 모델 제공자와 모델을 추가하고, Machines에서 이 컴퓨터를 연결한 후 프로젝트에 둘 다 공유하세요. CLI를 인스턴스로 지정하세요:

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

agent.yaml에서 제공자 및 모델 이름을 사용하고 machine_pool_name을 machine_name: <your machine>으로 바꾸세요.

TypeScript SDK

대시보드에서 API 키를 생성하고 OMNARA_TOKEN으로 내보낸 후 npm install @omnara/sdk로 설치하세요. 그런 다음:

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

전체 코드베이스는 Apache 2.0 라이선스이며 Docker Compose를 통해 단일 머신에서 셀프 호스팅할 수 있습니다. 상태와 모델을 호스팅 제공자에게 넘기지 않고 관리형 에이전트의 편의성을 원하는 개발자를 대상으로 합니다.