Public deployment runbook (P0: trusted distribution)
Which document is this? This one is the step-by-step runbook: the configuration, reverse proxy, key distribution, workers, backup, and go-live checklist for putting a gateway on the public internet today. For the reasons behind it (what blocked going public, who is isolated from whom, and what P1 and P2 will add), see the design document public-deployment.md. Where the two overlap, this runbook is the operational authority.
Scope: putting one OAA gateway on the public internet for callers you know and trust ("form A" in the plan, see §3 of public-deployment.md). Public calls aimed at strangers need a production-grade execution sandbox, which is not yet available (an optional process-level
sandboxexecution level exists; see sandbox-design.md).All commands and configuration in this document are examples to run on your own server. This repository will not do any deployment, DNS, certificate, firewall, or port operation for you.
1. Confirm before deploying
- Which agents will be published on this gateway? Do not open native agents (Codex, Claude, Antigravity, DSH) to untrusted callers. They inherit all the host's privileges, and a caller can make them read or write anything on this machine that they can reach.
- The model credentials are each vendor's API key, not the sign-in state of a personal subscription.
- The compliance requirements of the target market are confirmed, for example ICP filing and generative AI service filing; see §13 of the plan.
- Prepare two domains:
api.<domain>for callers andconsole.<domain>for the management plane. Below,api.example.comandconsole.example.comstand in for them.
2. Architecture
caller SDK / MCP ──HTTPS──▶ reverse proxy (TLS) ──▶ gateway 127.0.0.1:8787
admin browser ──HTTPS──▶ the same reverse proxy (console domain, source IPs restricted)
publisher worker ──outbound WSS──▶ api.example.com/v1/nodes/connect- The gateway listens only on
127.0.0.1, and a reverse proxy on the same machine serves it to the outside. - A worker connects to the gateway on its own initiative, and the network it sits in does not need to open any inbound port.
3. Install the gateway
Node.js 24.18 or newer on the 24 or 26 line is required.
npm ci --omit=optional --ignore-scriptsnpm run buildnpm run oaa -- init --dir /srv/oaa/datainit generates /srv/oaa/data/config.json and admin.token, with file permissions that make them readable only by the current user. admin.token is the owner-level admin key; do not give it to any caller.
4. Gateway configuration
Add or change the following fields in config.json, and leave the rest as init generated it:
{
"host": "127.0.0.1",
"port": 8787,
"publicBaseUrl": "https://api.example.com",
"trustProxy": true,
"allowedHosts": ["api.example.com", "console.example.com"],
"allowedOrigins": ["https://console.example.com"],
"consoleHosts": ["console.example.com"],
"maxActiveRunsPerSubject": 4,
"defaultKeyExecution": "workspace"
}| Field | Purpose |
|---|---|
host: 127.0.0.1 | Reachable only by the reverse proxy on this machine, not exposed directly |
publicBaseUrl | The endpoint catalog returned by GET /v1/me is generated from this address |
trustProxy | Reads X-Forwarded-Proto/Host and X-Forwarded-For (the source IP used by audit records and developer platform rate limiting). Turn it on only when there really is a reverse proxy in front |
allowedHosts | Responds only to these Hosts; everything else gets 403 invalid_host |
consoleHosts | The console and admin keys are usable only on these domains (see "Management plane and API domain separation" in docs/protocol.md) |
maxActiveRunsPerSubject | How many unfinished requests each caller may have at the same time; the owner total limit is still 32 |
defaultKeyExecution | A newly created key can by default call only agents of the workspace level, and cannot call native agents, adapters, or host tools. When truly needed, specify "execution": "host" explicitly when creating the key, and only for trusted parties |
If the gateway has its own local worker (localWorker) and will enable native agents or adapters, we recommend turning on the environment variable allowlist:
{
"localWorker": {
"nativeEnv": { "mode": "allowlist", "allow": ["ANTHROPIC_API_KEY"] }
}
}In allowlist mode a child process receives only these variables:
- Base variables:
PATH,HOME,LANG,TMPDIR, and so on, plusLC_*. - Proxy variables:
HTTP(S)_PROXY,ALL_PROXY,NO_PROXY, passed through as is, so network behavior is the same before and after turning it on. - The variables you list in
allow.
OAA_* is never passed to a child process in any mode. The default inherit mode is the same as before and inherits all other variables.
5. Reverse proxy
Requirements:
- Support for HTTP/1.1 Upgrade, which workers' WSS connections need.
- Long connections do not time out, or the timeout is not shorter than the longest duration of a single run. The gateway's SSE sends a heartbeat every 15 seconds.
- A request body limit of no less than 24 MiB.
- Forward
Hostas is, and overwrite theX-Forwarded-*headers the client brings, and never pass through values sent by the client. - Static assets such as fonts are served by the gateway, and font files carry long cache headers (
immutable), so no special configuration is needed. If the proxy only lets fixed paths through, allow/styles/,/shared/,/fonts/, and under the portal/portal/styles/,/portal/shared/,/portal/fonts/.
Caddy example (certificates are obtained and renewed automatically):
api.example.com {
request_body {
max_size 24MB
}
reverse_proxy 127.0.0.1:8787 {
flush_interval -1
}
}
console.example.com {
@outside not remote_ip 203.0.113.0/24
respond @outside 403
reverse_proxy 127.0.0.1:8787
}Nginx example (certificate configuration omitted):
server {
server_name api.example.com;
client_max_body_size 24m;
location / {
proxy_pass http://127.0.0.1:8787;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_set_header X-Forwarded-Host $host;
proxy_set_header X-Forwarded-For $remote_addr;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 3600s;
proxy_buffering off;
}
}Nginx's $connection_upgrade must be defined in the http block with map $http_upgrade $connection_upgrade { default upgrade; '' close; }. Write another block for console.example.com in the same way, and restrict source IPs with allow / deny.
In addition, oaa tunnel can use cloudflared to produce a temporary public address, which suits demos and is not recommended for long-term use.
6. Start
npm run oaa -- serve --config /srv/oaa/data/config.json --detach--detach confirms that the background process has started, and the PID and log are written in the data directory. If you need it to start at boot, run serve without --detach under a process manager such as systemd.
After it starts, check on the server:
curl -s http://127.0.0.1:8787/healthAccessed directly on the machine it returns pid. Accessed through https://api.example.com/health there is no pid, which is expected.
7. Distribute caller keys
Give each caller a separate key, created on the console domain:
curl -s https://console.example.com/v1/keys \
-H "Authorization: Bearer $(cat /srv/oaa/data/admin.token)" \
-H 'Content-Type: application/json' \
-d '{"name":"partner-a","agents":["agent/research"],"scopes":["invoke","read","files"],"quota":{"rpm":60,"maxConcurrentRuns":2}}'- The returned
tokenis shown only this once; hand it over through a secure channel. - The default
data_scopeisown: a caller can see only their own runs, files, and memory, isolated from each other (see "Caller data isolation" indocs/protocol.md). - For a key that needs to see all callers' data, such as a read-only monitoring dashboard, add
"data_scope": "owner"when creating it, and grant only thereadscope. - Do not give callers the
adminscope. OnceconsoleHostsis configured, an admin key cannot be used on the API domain either. - Denied calls (permission, isolation, quota) go into the audit records, which you can view with an admin key on the console domain through
GET /v1/audit.
How a caller writes it:
from openai import OpenAI
client = OpenAI(base_url="https://api.example.com/v1", api_key="the key given to them")
response = client.responses.create(model="agent/research", input="Analyze these materials.")If you want callers to use their own model quota, add "byok": true in the worker's provider configuration (see "Caller-supplied model keys" in docs/protocol.md). The caller then brings their own key in a request header:
client = OpenAI(
base_url="https://api.example.com/v1",
api_key="the key given to them",
default_headers={"X-OAA-Provider-Key": "the caller's own model provider key"},
)Note: once byok is on, the caller's key is sent to the baseUrl configured for that provider, so turn it on only for upstream addresses you trust.
Distributing through the developer platform
If you want developers to register and create keys themselves, instead of you handing them out one by one, you can configure the platform section to enable the developer platform (for the configuration and interfaces see platform.md). Then:
- Developers register, redeem credits, and create their own API keys in the portal
https://api.example.com/portal/. The scopes of keys created in the portal are fixed toinvoke,read, andfiles, with noadmin. The execution level is decided byplatform.keyExecutionand can only beworkspaceorsandbox. - Developers can call only the agents you have listed and enabled on the console's "Developer platform" page.
- Credits are issued by you (redemption codes or manual adjustment); the platform does not take payments.
- Do not list native agents (Codex, Claude, Antigravity, DSH). They run with host privileges, and a key of the
workspacelevel cannot call them anyway (seedefaultKeyExecutionin §4). - Account keys do not appear in the list of
GET /v1/keys.
8. Connect a remote worker
- Register the node on the console domain:
POST /v1/nodes/enroll, with the request body{"node_id":"workstation-2","agents":["agent/research"],"capabilities":["*"]}. The returnedtokenis the node credential, completely separate from caller keys. - Write the configuration on the worker machine, with
gatewayUrlset tohttps://api.example.comandtokenFilepointing to the node credential obtained in the previous step. For the full format see "Workers" in operations.md. - Run on the worker machine:
npm run oaa -- node join --config /private/path/worker.jsonYou can use oaa node drain, oaa node resume, and oaa node revoke to pause, resume, or revoke a node.
9. Backup, upgrade, and rollback
- All data is in the data directory:
state.sqliteplusfiles/. For a backup, stop the gateway first, or use SQLite's online backup (VACUUM INTO), and do not directly copy a database file that is being written while the gateway runs. - Upgrading to schema v4 makes a backup automatically, at
<dataDir>/backups/state-v<old version>-before-subjects-<timestamp>.sqlite. v4 cannot be opened by an older gateway (it reportsschema_too_new). To roll back: stop the new gateway, copy the backup back overstate.sqlite, and start the old version. - After the upgrade, non-admin read-only keys created before can by default see only their own data. Those that need a global view should be recreated with
data_scope: "owner".
10. Go-live checklist
- From the public internet, accessing
https://api.example.com/returns 404, and/healthreturns 200 withoutpid. - From the public internet, accessing
https://api.example.com/v1/agentswith an admin key returns 403admin_host_denied. - Create a run with caller key A and read it with key B: it returns 404
run_not_found. - Accessing with a forged Host (for example
curl -H 'Host: evil.example.net') returns 403invalid_host. - At least one remote worker has connected over WSS and completed a run successfully.
- The data directory already has a backup, and a restore has actually been rehearsed once.
- Send one non-streaming call to
https://api.example.com/v1with the official OpenAI SDK and confirm the result is normal; then call an agent that does not exist and confirm the error the SDK raises carrieserror.code. - Disconnect a run's event stream midway (for example close
GET /v1/responses/{id}?stream=truehalfway through reading), and after reconnecting you can receive the terminal event.
11. Known limitations (outside the scope of P0)
- There is no sandbox by default. Native agents and host scripts run with the host's privileges. An optional process-level
sandboxexecution level now exists (srt; script tools, and in code Claude and Codex, which has not yet been tested with the real CLIs), but it is not yet isolation fit for strangers at scale; see sandbox-design.md. - A single gateway with SQLite cannot scale horizontally and has no failover; that is P2.
- Each key's RPM count is in process memory and resets to zero on restart.
- Billing and self-service registration are available only after configuring
platform(see platform.md). Credits are issued by the operator; there is no payment channel and no email: there is no email verification, and passwords are reset by the operator.