orpheus

module
v0.6.2 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: MIT

README

Orpheus

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. The copied configuration already registers orpheus-codex. To allow another AgentBox template, add its exact name to orpheus.toml, for example:

[templates."orpheus-codex:v1.2.0"]
description = "Pinned sandbox"

At least one template is required; each key is its exact AgentBox name, including any tag.

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

The API is available at http://localhost:8000. By default, session requests require Authorization: Bearer <key> using a key from PUBLIC_API_KEYS in .env. For read-only browser access, see browser authentication. For the dashboard snapshot and session filters, see dashboard analytics. For profile settings, template registration and catalog APIs, see profiles and templates. For provider quota snapshots by account, see account limits. For database-backed Prometheus metrics on the internal system listener, see service metrics. Run make stop to stop the project; database data is preserved.

Run and hook deadlines are independent of the sandbox timeout. The worker creates and reconnects sandboxes with a five-minute lease and renews it once per minute while preparing, executing or finalizing a run. A one-hour run does not require requesting more than one hour from AgentBox to cover hooks and cleanup. If the worker stops renewing, AgentBox auto-pauses the sandbox when the lease expires; after a run, Orpheus deletes a single-run sandbox or pauses a reusable one. The AgentBox plan's maximum uninterrupted sandbox lifetime still applies: lease renewal does not extend that limit.

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.

Service access

Define named groups of worker ENV names in orpheus.toml:

[services.helpdesk]
name = "Helpdesk"
description = "Read tickets and publish replies."
env_from = ["HELPDESK_URL", "HELPDESK_TOKEN"]

Supply values to the worker. GET /api/v1/services returns the catalog without secret values. Select codes in configuration.sandbox.services for the agent and session hooks, or top-level services for only that run's before_run and after_run. Services combine with env_from. Their ENV names also join the explicit HARNESS_ENV_ALLOWLIST on API and worker. No service is automatically selected. Unknown codes reject the request with 422 unknown_service.

Accepted sessions and runs retain service snapshots. Catalog edits apply to new sessions and runs, not existing snapshots. See the service setup guide.

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-saml Signed SAML round trip through the production HTTP handler and isolated Keycloak; no UI required
make test-live Manually run real AgentBox/Codex, lost-response recovery, reconnect and account-file checks; not run by CI
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
accountlimits
Package accountlimits normalizes provider quota snapshots without depending on transport or storage.
Package accountlimits normalizes provider quota snapshots without depending on transport or storage.
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.
analytics
Package analytics defines the dashboard snapshot independently of HTTP DTOs.
Package analytics defines the dashboard snapshot independently of HTTP DTOs.
api
Package api provides primitives to interact with the openapi HTTP API.
Package api provides primitives to interact with the openapi HTTP API.
browserauth
Package browserauth implements read-only browser identity and SP-initiated SAML.
Package browserauth implements read-only browser identity and SP-initiated SAML.
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