orpheus

module
v0.1.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 23, 2026 License: MIT

README

Orpheus

The orchestrator of AI agents working in AgentBox sandboxes. Implemented in Go 1.27 with PostgreSQL 16.

Quick start

Requirements: Docker with Compose v2.24 or newer, and Make.

cp .env.dist .env
cp orpheus.toml.dist orpheus.toml

Set AGENTBOX_API_KEY and OPENAI_API_KEY in .env. Add model = "your-model" under [profiles.default] in orpheus.toml.

make start
curl -fsS http://localhost:8000/ready

The API is available at http://localhost:8000. Session requests require Authorization: Bearer <key> using a key from PUBLIC_API_KEYS in .env. Run make stop to stop the project; database data is preserved.

Go API client

Connectors import github.com/orpheus-agents/orpheus/client. The public HTTP client and wire types are generated from api/openapi.yaml with the pinned oapi-codegen version. No server startup, database connection or connector-side generation is needed.

The client belongs to the root Go module and uses the same vX.Y.Z release tag as Orpheus. Pin a tag containing the client with go get github.com/orpheus-agents/orpheus/client@<release-tag>; v0.1.0 predates it. See client usage for authentication, responses and SSE.

Regular CI runs make check, including client generation, tests and compilation. Tag pushes run only make build-client before publishing the image; generation checks and tests are not repeated on tags. Go consumers obtain the source from the Git tag: a separate binary or package registry upload is unnecessary. Generation happens before committing; CI rejects stale output instead of silently generating a different release. Go module publishing.

Development

The application, generators, linters and tests run in Docker; host Go and Python are not required.

On Linux, Make uses the host UID/GID for development containers. Override with ORPHEUS_UID=1000 ORPHEUS_GID=1000 make <target> when needed; other hosts default to 1000:1000.

The migrate command reads migrations/ relative to the container's working directory. Use migrate --dir /path/to/migrations up or ORPHEUS_MIGRATIONS_DIR to select another directory inside the container.

Command Purpose
make tools / make tools-build Ensure the matching tools image exists / explicitly rebuild it
make start / make stop Start or stop Compose services; preserve database volumes
make migrate Apply Goose migrations from migrations/
make generate Generate OpenAPI server, public Go client and sqlc queries/models
make generate-check Compare all generated content, including missing/obsolete files, without changing the checkout
make generate-client / make generate-client-check Generate / check only the Go client; no SQL generation
make test-client / make build-client Test the client with the race detector / compile the package
make sqlc-check Prepare all SQL queries against an isolated PostgreSQL schema created by Goose
make fix / make gofix Format Go / apply Go toolchain fixes
make tidy-check Check go.mod and go.sum with go mod tidy -diff, without modifying files
make deadcode Reject unreachable Go functions, including test entrypoints and integration/live build tags
make lint Go, OpenAPI, Dockerfile and Python reader checks
make test Unit, reader, PostgreSQL, S3 and migration tests
make test-go-race Unit and integration tests with the race detector
make test-live Real AgentBox/Codex, lost-response recovery, reconnect and account-file checks
make vuln govulncheck and Trivy vulnerability/configuration scans
make build Compile the application inside the tools container
make docker-build / make smoke Build images / verify production serve, worker, migrate and shutdown
make check Check generation, module tidiness, Go fixes, lint, dead code, SQL, tests, race, vulnerabilities and compilation

Directories

Path Synopsis
Package client provides primitives to interact with the openapi HTTP API.
Package client provides primitives to interact with the openapi HTTP API.
cmd
orpheus command
orpheus-hook-runner command
Command orpheus-hook-runner records a sandbox hook's result across worker restarts.
Command orpheus-hook-runner records a sandbox hook's result across worker restarts.
internal
agentbox
Package agentbox adapts the official SDK to the executor's narrow I/O contract.
Package agentbox adapts the official SDK to the executor's narrow I/O contract.
api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
config
Package config resolves deployment profiles into immutable execution snapshots.
Package config resolves deployment profiles into immutable execution snapshots.
credentials
Package credentials synchronizes account auth files between S3 and a sandbox.
Package credentials synchronizes account auth files between S3 and a sandbox.
diagnostic
Package diagnostic reports error identity without native messages or secrets.
Package diagnostic reports error identity without native messages or secrets.
harness
Package harness defines the process and history operations used by the executor.
Package harness defines the process and history operations used by the executor.
harness/codex
Package codex implements app-server RPC and durable native-history recovery.
Package codex implements app-server RPC and durable native-history recovery.
httpserver
Package httpserver implements the generated HTTP contract.
Package httpserver implements the generated HTTP contract.
migrate
Package migrate applies the Goose SQL files shipped with the application.
Package migrate applies the Goose SQL files shipped with the application.
secret
Package secret encrypts explicit sandbox environment values at rest.
Package secret encrypts explicit sandbox environment values at rest.
session
Package session defines the durable, harness-neutral session model.
Package session defines the durable, harness-neutral session model.
store
Package store owns PostgreSQL transactions, admission, and durable projections.
Package store owns PostgreSQL transactions, admission, and durable projections.
worker
Package worker executes sessions concurrently under a single database owner.
Package worker executes sessions concurrently under a single database owner.
tools
generate command
Command generate derives transport code, the embedded specification, and SQL queries.
Command generate derives transport code, the embedded specification, and SQL queries.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL