Deployment

Dev and server modes

rebuno dev runs entirely in memory with auth disabled. It is for local development only, and nothing persists across restarts. rebuno server is the production kernel. It requires Postgres and a bearer token and refuses to start without them:

rebuno server \
  --db-url "postgres://USER:PASSWORD@localhost:5432/rebuno" \
  --bearer-token "$REBUNO_BEARER_TOKEN" \
  --config /etc/rebuno/agents.yaml

The schema is applied from embedded migrations on boot. The HTTP API is stateless, so you scale by running more replicas behind a load balancer. Postgres is the only coordination point, and singleton background work (approval expiry, execution deadlines, cleanup) is leader-elected through a Postgres advisory lock.

Authentication

Client and admin routes accept scoped API keys, OIDC tokens, or the full-access bootstrap bearer token:

curl -X POST http://localhost:8080/v0/executions \
  -H "Authorization: Bearer $REBUNO_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "researcher", "input": {"query": "hello"}}'

Both SDK clients read the token from REBUNO_API_KEY if you do not pass it explicitly. Agent routes do not use the bearer token at all. They authenticate with HMAC over the agent’s registered secret. See Authentication.

OIDC

Set REBUNO_OIDC_ISSUER and REBUNO_OIDC_AUDIENCE to accept JWTs from your identity provider. The kernel discovers the issuer’s signing keys on boot and rejects tokens with a different issuer or audience, so give each deployment its own audience. The caller is identified as user:<claim> from REBUNO_OIDC_USER_CLAIM, and its scopes are the union of those mapped to its groups:

REBUNO_OIDC_ISSUER=https://corp.okta.com/oauth2/default
REBUNO_OIDC_AUDIENCE=rebuno-prod
REBUNO_OIDC_GROUP_SCOPES='{
  "platform-admins": ["*"],
  "support": ["executions:read", "executions:write", "approvals:read", "approvals:write"],
  "auditors": ["executions:read", "approvals:read"]
}'

"*" grants every scope. A user in no mapped group authenticates but is refused every route with 403 forbidden.

Access

--access / REBUNO_ACCESS_CONFIG names a file granting roles on each agent. Keys are agent IDs, with "*" applying to every agent; each role lists principals as user:<claim>, service:<api key id>, or group:<oidc group>:

"*":
  read: ["group:auditors"]

code:
  write: ["group:support", "user:alice@corp.com"]
  approve: ["group:platform"]
  admin: ["group:platform-admins"]

Role	Grants
`read`	Read the agent, its executions, steps, events, streams, and approvals.
`write`	`read`, plus create, cancel, and fork executions.
`approve`	`read`, plus grant and deny approvals.
`admin`	Everything, including registering or deleting the agent and loading or testing its policy.

A request needs both the route’s scope and a role on the agent. Listings return only agents the caller can read and their executions and approvals. With a file configured, API keys and OIDC users without a role on an agent are refused with 403 forbidden; without one, scopes alone decide. The bootstrap token holds every role, and agents keep access to their own executions. The kernel logs a warning on boot for agent IDs that are not registered.

Security log

The security log records who administered Rebuno and who was refused access to it. --security-log / REBUNO_SECURITY_LOG writes one JSON line per entry to stdout, stderr, or a file, which it appends to. Unset, the security log is off. Each entry carries time, the action as msg, and the acting principal (admin, service:<api key id>, user:<claim>, agent:<id>, or anonymous):

{"time":"2026-10-15T19:30:02Z","level":"INFO","msg":"policy.load","principal":"user:alice@corp.com","agent":"code","bundle_sha256":"9f2c…"}

Action	Fields
`kernel.start`	`replica`, `oidc_issuer`, `oidc_audience`, `access_config_sha256`
`api_key.create`, `api_key.rotate`, `api_key.revoke`	`key_id`; `name` and `scopes` on create
`agent.register`, `agent.delete`	`agent`; `webhook_url` on register
`policy.load`	`agent`, `bundle_sha256` (empty when the policy is cleared)
`approval.grant`, `approval.deny`	`approval_id`, `execution_id`, `decided_by`, `asserted_by`
`execution.cancel`	`execution_id`
`execution.impersonate`	`execution_id`, `agent`, `on_behalf_of`
`request.denied`	`method`, `path`, `status` (`401` or `403`)

Entries are written after the action succeeds. Each replica writes its own. Write to a file on a persistent volume, or collect stdout with a log shipper: entries written to a container’s stdout are lost when the container is replaced.

Provisioning agents

Register agents and their policies declaratively with --config, a manifest both dev and server load on boot and upsert. See examples/rebuno.dev.yaml:

agents:
  - id: researcher
    webhook_url: https://researcher.internal/webhook
    secret: ${RESEARCHER_SECRET}
    lease_timeout_seconds: 600            # omit to use the kernel default
    policy_file: policies/research.yaml   # or an inline `policy: |` block

policy_file paths resolve relative to the manifest. A malformed bundle fails the boot, so a broken policy never falls back to permissive. An entry without a policy keeps the agent’s current one. You can also register agents and load policy at runtime over the admin API.

Configuration

Server flags and their environment-variable equivalents:

Flag	Env	Default	Description
`--listen-addr`	`REBUNO_LISTEN_ADDR`	`:8080`	HTTP listen address.
`--db-url`	`REBUNO_DB_URL`	none	Postgres URL. Required in server mode.
`--bearer-token`	`REBUNO_BEARER_TOKEN`	none	Client/admin API token. Required in server mode.
`--config`	none	none	Provisioning manifest path.
`--db-max-conns`	`REBUNO_DB_MAX_CONNS`	auto	Max DB pool connections.
`--db-min-conns`	`REBUNO_DB_MIN_CONNS`	auto	Min DB pool connections.
`--log-level`	`REBUNO_LOG_LEVEL`	`info`	`debug`/`info`/`warn`/`error`.
`--log-format`	`REBUNO_LOG_FORMAT`	`text`	`text` or `json`.
`--otel-endpoint`	`REBUNO_OTEL_ENDPOINT`	none	OTLP gRPC endpoint (empty turns tracing off).
`--otel-sample-rate`	`REBUNO_OTEL_SAMPLE_RATE`	`1.0`	Trace sampling rate.
`--otel-insecure`	`REBUNO_OTEL_INSECURE`	`false`	Plaintext OTLP connection.
`--access`	`REBUNO_ACCESS_CONFIG`	none	Per-agent access file. See Access.
`--security-log`	`REBUNO_SECURITY_LOG`	none	`stdout`, `stderr`, or a file path. See Security log.

Additional environment-only settings:

Env	Default	Description
`REBUNO_DISPATCH_MAX_ATTEMPTS`	`5`	Webhook delivery attempts before exhaustion.
`REBUNO_DISPATCH_TIMEOUT`	`30s`	Per-attempt webhook timeout.
`REBUNO_DISPATCH_CONCURRENCY`	`8`	Deliveries in flight per replica, and the most rows one claim takes.
`REBUNO_DISPATCH_LEASE_TIMEOUT`	`2m`	How long a claimed dispatch stays owned before the reaper reclaims it. Reclamation runs every two seconds, or four times per lease period if that is sooner.
`REBUNO_DEADLINE_TIMEOUT`	none	Max execution lifetime before auto-cancel.
`REBUNO_DEADLINE_CHECK_INTERVAL`	`30s`	How often expired executions are cancelled. Set to `0` to fold this into the `REBUNO_CLEANUP_INTERVAL` sweep.
`REBUNO_APPROVAL_TIMEOUT`	`15m`	Default time an approval can stay pending. On expiry the gated step is denied with `approval_timeout` and the execution resumes.
`REBUNO_CLEANUP_INTERVAL`	`10m`	How often the singleton worker runs approval expiry, deadline cancellation, and the retention sweep.
`REBUNO_RETENTION`	`24h`	Creation-age cutoff for deleting terminal executions. Pending, running, and blocked executions are retained, and so is every execution in a session that has one retained.
`REBUNO_LEADER_LOCK_KEY`	`rebuno_scheduler_leader`	Advisory-lock key for leader election.
`REBUNO_JUDGE_CONFIG`	none	Path to the decision model config for policy rules that decide `judge`. Without it, those rules deny. See Judge.
`REBUNO_OIDC_ISSUER`	none	OIDC issuer URL. Enables OIDC bearer tokens. See OIDC.
`REBUNO_OIDC_AUDIENCE`	none	Required `aud` claim. Required with `REBUNO_OIDC_ISSUER`.
`REBUNO_OIDC_USER_CLAIM`	`email`	Claim naming the user, e.g. `preferred_username` or `sub`.
`REBUNO_OIDC_GROUPS_CLAIM`	`groups`	Claim listing the user’s groups.
`REBUNO_OIDC_GROUP_SCOPES`	none	JSON object mapping group names to scopes.

Load balancer

Set the balancer’s read timeout below the client’s, so it fails over to another replica before the client gives up. Both SDK clients default to 35 seconds. Point pool health checks at /v0/ready, which returns 503 when a dependency is down; /v0/health answers ok regardless.

upstream rebuno {
    server kernel-1:8080;
    server kernel-2:8080;
    server kernel-3:8080;
}

server {
    location / {
        proxy_pass http://rebuno;
        proxy_connect_timeout 2s;
        proxy_read_timeout 20s;
    }
}

Execution streams (GET /v0/executions/{id}/stream) are server-sent events. The kernel sets X-Accel-Buffering: no; a balancer that ignores it needs response buffering disabled for that path.

Docker

The image is built from deploy/Dockerfile and published to ghcr.io/rebuno/rebuno on tagged releases. Its entrypoint is rebuno server, so pass configuration as flags or REBUNO_* environment variables:

docker run -p 8080:8080 \
  -e REBUNO_DB_URL="postgres://…" \
  -e REBUNO_BEARER_TOKEN="…" \
  ghcr.io/rebuno/rebuno:latest

Observability

Tracing (OpenTelemetry): every API request and dispatch attempt, correlated by execution_id and step_id. Enable with --otel-endpoint.
Metrics (Prometheus): scrape /metrics for execution counts by status, dispatch attempts, queue depth, approval wait times, replay-hit rate, and policy latency.
Logging: structured, with execution_id and step_id correlation.

Get started

Concepts

Integrations

Operations

Dev and server modes

Authentication

OIDC

Access

Security log

Provisioning agents

Configuration

Load balancer

Docker

Observability

​Dev and server modes

​Authentication

​OIDC

​Access

​Security log

​Provisioning agents

​Configuration

​Load balancer

​Docker

​Observability

Dev and server modes

Authentication

OIDC

Access

Security log

Provisioning agents

Configuration

Load balancer

Docker

Observability