Deployment

This guide describes the public runtime contract for self-hosting Omnigraph. It does not include environment-specific secrets, private infrastructure, or internal deploy automation.

Runtime modes

Omnigraph supports two broad deployment shapes:

• local directory graphs
• s3:// graphs on AWS S3 or S3-compatible object stores

The server binary and container image expose the same HTTP surface.

Binary deployment

Install or build:

• omnigraph
• omnigraph-server

Run against a local graph:

omnigraph-server ./graph.omni --bind 0.0.0.0:8080

Run against an object-store-backed graph:

OMNIGRAPH_SERVER_BEARER_TOKEN="change-me" \
AWS_REGION="us-east-1" \
omnigraph-server s3://my-bucket/graphs/example/releases/2026-04-10-v0.1.0 \
  --bind 0.0.0.0:8080

One-command local RustFS bootstrap

The fastest local S3-backed deployment path is:

curl -fsSL https://raw.githubusercontent.com/ModernRelay/omnigraph/main/scripts/local-rustfs-bootstrap.sh | bash

The bootstrap:

• starts a local RustFS-backed object store
• creates a bucket and S3-backed Omnigraph graph
• loads the checked-in context fixture
• starts omnigraph-server on 127.0.0.1:8080

Supported behavior:

• downloads the rolling edge binary when one exists for the current platform
• otherwise clones ModernRelay/omnigraph and builds from source
• reuses an existing RustFS container if it is already running

Useful overrides:

• WORKDIR=/path/to/state
• BUCKET=omnigraph-local
• PREFIX=repos/context
• BIND=127.0.0.1:8080
• RUSTFS_CONTAINER_NAME=omnigraph-rustfs-demo
• RESET_REPO=1. Destroy and recreate the bucket/graph before loading. Use sparingly; this is destructive.

The bootstrap expects:

• Docker
• curl
• either a matching release asset or a local Rust toolchain plus git

If aws is not installed, the script attempts a user-local AWS CLI install via python3 -m pip. Docker Desktop or another Docker daemon must already be running.

Container deployment

Build the image:

docker build -t omnigraph-server:local .

Run against a local graph:

docker run --rm -p 8080:8080 \
  -v "$PWD/graph.omni:/data/graph.omni" \
  omnigraph-server:local \
  /data/graph.omni --bind 0.0.0.0:8080

Run against an S3-backed graph:

docker run --rm -p 8080:8080 \
  -e OMNIGRAPH_SERVER_BEARER_TOKEN="change-me" \
  -e AWS_REGION="us-east-1" \
  omnigraph-server:local \
  s3://my-bucket/graphs/example/releases/2026-04-10-v0.1.0 \
  --bind 0.0.0.0:8080

Build variants

Two omnigraph-server build variants are published per platform:

• default. Local + S3-compatible storage; suitable for self-hosted setups.
• --features aws. Adds AWS Secrets Manager integration for bearer tokens. Released as omnigraph-server-<version>-<platform>-aws.tar.gz.

Build the AWS variant from source with:

cargo build --release --locked --features aws -p omnigraph-server

Auth

The server can run unauthenticated for local development. Any shared or internet-facing deployment should configure bearer tokens.

Token sources

The server reads bearer tokens from one of four sources, in priority order:

The first source that resolves wins. Multi-token sources additionally bind each token to an actor identity, which Cedar policy (if configured) uses for authorization decisions.

AWS Secrets Manager

When running the aws build, point the server at a Secrets Manager secret containing JSON of the form {"<token>": "<actor>"}:

OMNIGRAPH_SERVER_BEARER_TOKENS_AWS_SECRET="prod/omnigraph/tokens" \
AWS_REGION="us-east-1" \
omnigraph-server s3://my-bucket/graphs/example --bind 0.0.0.0:8080

The secret is fetched at process startup; rotate it by restarting the server.

Per-actor admission control

Once tokens map to actors, the server caps concurrency per actor. The defaults are sane for most deployments, but they are tunable:

• OMNIGRAPH_PER_ACTOR_INFLIGHT_MAX. Max simultaneous in-flight requests for a single actor.
• OMNIGRAPH_PER_ACTOR_BYTES_MAX. Max simultaneous in-flight request bytes for a single actor.

When either ceiling is hit, additional requests from that actor return HTTP 429 with a Retry-After header so well-behaved clients back off.

The health endpoint /healthz remains suitable for load balancer health checks.

S3-compatible storage

For S3-compatible backends such as RustFS or MinIO, set the usual AWS SDK environment variables:

• AWS_ACCESS_KEY_ID
• AWS_SECRET_ACCESS_KEY
• AWS_REGION
• optional AWS_ENDPOINT_URL
• optional AWS_ENDPOINT_URL_S3
• optional AWS_ALLOW_HTTP=true
• optional AWS_S3_FORCE_PATH_STYLE=true