Publishing an Agent

Overview

Publishing exposes one conductor profile over a public HTTPS surface served by the separate chat-gateway binary. This guide walks operators through the full lifecycle: configuration, publish, key issuance, calling the surface, rotation, and revoke. See Publishing for the conceptual model.

Prerequisites

A running conductor with Postgres and Redis wired up
A non-superuser Postgres application role with NOBYPASSRLS
A profile that already runs cleanly under conductor (POST /api/runs works)
DNS for the public chat host pointed at the chat-gateway service (for example agents.example.com)
Two base64 secrets minted ahead of time:
- Signing key — shared HMAC secret between gateway and conductor
- API key pepper — HMAC pepper used to hash minted bearers

Generate both with:

openssl rand -base64 32   # signing key
openssl rand -base64 32   # API key pepper

Step 1 — Configure Conductor for the Internal Listener

The conductor now serves two listeners: the public dashboard port and a private INTERNAL_PORT that only the chat gateway should reach.

Variable	Required	Description
`INTERNAL_PORT`	Yes	Private listener port; only routes used by the gateway are mounted
`CHAT_GATEWAY_SIGNING_KEY_CURRENT`	Yes	Base64 HMAC secret; conductor verifies every internal request
`CHAT_GATEWAY_SIGNING_KEY_PREVIOUS`	No	Previous key during rotation; accepted in parallel
`AGENT_API_KEY_PEPPER`	Yes	Base64 HMAC pepper; hashes minted public tokens
`CHAT_GATEWAY_PUBLIC_HOST`	Yes	Externally-advertised gateway host; appears in `publicUrl`
`REDIS_URL`	Recommended	Backs the nonce-replay store; falls back to in-memory when unset

The conductor refuses to start when INTERNAL_PORT is set but CHAT_GATEWAY_SIGNING_KEY_CURRENT is missing — that combination would silently accept unsigned internal traffic.

Postgres Role Requirement

When Postgres is configured, the conductor refuses to boot if the connecting role is a SUPERUSER or has BYPASSRLS. Tenanted tables rely on row-level security policies scoped by the per-transaction app.tenant_id setting, so a privileged role would silently read rows across tenants. Railway’s default postgres user is a superuser; create and use an application role instead.

create role app_conductor login password '<strong-random>' nobypassrls;
grant connect on database <dbname> to app_conductor;
grant usage, create on schema public to app_conductor;
grant select, insert, update, delete on all tables in schema public to app_conductor;
grant usage, select on all sequences in schema public to app_conductor;
alter default privileges in schema public
  grant select, insert, update, delete on tables to app_conductor;
alter default privileges in schema public
  grant usage, select on sequences to app_conductor;

Point POSTGRES_DSN or the POSTGRES_USER / POSTGRES_PASSWORD component variables at that role. The CREATE privilege is required because the conductor applies embedded schema migrations on boot.

Step 2 — Deploy the Chat Gateway

The gateway is a standalone binary (cmd/chat-gateway). The reference Dockerfile is at docker/Dockerfile.chat-gateway; the Railway service config is at docker/railway-chat-gateway.toml.

Variable	Required	Description
`PORT`	No	Public listen port; defaults to `8090`
`CONDUCTOR_INTERNAL_URL`	Yes	Private conductor URL; `*.railway.app` public URLs are rejected at boot
`POSTGRES_URL` (or `PG*`)	Yes	Same Postgres cluster as conductor, using a non-superuser `NOBYPASSRLS` application role
`REDIS_URL`	Recommended	Nonce store and rate-limit counters
`CHAT_GATEWAY_SIGNING_KEY_CURRENT`	Yes	Must match the conductor’s current key
`CHAT_GATEWAY_SIGNING_KEY_PREVIOUS`	No	Match the conductor’s previous key during rotation
`AGENT_API_KEY_PEPPER`	Yes	Same pepper as the conductor
`CHAT_GATEWAY_PUBLIC_HOST`	No	Externally-advertised host; logged on boot
`GATEWAY_RATE_LIMIT_BACKEND`	No	`redis` (default) or `memory`
`GATEWAY_SHUTDOWN_GRACE`	No	Graceful shutdown timeout; defaults to `25s`

The gateway also refuses a Postgres role that is a SUPERUSER or has BYPASSRLS, for the same tenant-isolation reason as the conductor. The boot log line chat-gateway.ready confirms conductor_internal_url, rate_limit_backend, and whether a previous signing key is present.

Step 3 — Publish a Profile

Publishing is a conductor API call against the public port. The dashboard “Publish” surface wraps the same endpoint; the curl examples below match it byte-for-byte.

curl -X POST https://conductor.example.com/api/profiles/general/publish \
  -H 'Authorization: Bearer ao_...' \
  -H 'Content-Type: application/json' \
  -d '{
        "slug": "general",
        "allowedOrigins": ["https://example.com"],
        "rateLimitRpm": 60,
        "syncMaxDurationSeconds": 90,
        "exposeToolEvents": false
      }'

The response includes the new pub_... row plus the publicUrl derived from CHAT_GATEWAY_PUBLIC_HOST:

{
  "id": "pub_abcd1234",
  "tenantId": "default",
  "profileName": "general",
  "slug": "general",
  "visibility": "private",
  "authMode": "api_key",
  "allowedOrigins": ["https://example.com"],
  "rateLimitRpm": 60,
  "syncMaxDurationSeconds": 90,
  "exposeToolEvents": false,
  "enabled": true,
  "publicUrl": "https://agents.example.com/v1/chat/default/general"
}

Slugs are immutable. To change a slug, unpublish and republish.

Step 4 — Mint an API Key

API keys are HMAC-hashed with the pepper; the plaintext token is returned exactly once and never recoverable. See API Keys for the auth model.

curl -X POST https://conductor.example.com/api/profiles/general/keys \
  -H 'Authorization: Bearer ao_...' \
  -H 'Content-Type: application/json' \
  -d '{"label": "production website"}'

{
  "id": "key_abcd1234",
  "publishedId": "pub_abcd1234",
  "label": "production website",
  "createdAt": "2026-05-15T10:00:00Z",
  "token": "ao_prod_abcd...22chars..."
}

Persist the token immediately. Re-fetching the keys list returns metadata only.

Step 5 — Call the Public Endpoint

Sync Chat

curl -X POST https://agents.example.com/v1/chat/default/general \
  -H 'Authorization: Bearer ao_prod_abcd...' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Hello"}'

{
  "conversation_id": "conv_abcd1234",
  "message": "Hi there.",
  "public_run_id": "prun_abcd1234"
}

Streaming Chat

curl -N -X POST https://agents.example.com/v1/chat/default/general/stream \
  -H 'Authorization: Bearer ao_prod_abcd...' \
  -H 'Content-Type: application/json' \
  -d '{"message": "Stream the answer"}'

event: delta
data: {"text":"Hi"}

event: delta
data: {"text":" there."}

event: done
data: {"conversation_id":"conv_abcd1234","message":"Hi there.","public_run_id":"prun_abcd1234"}

Continuing a Conversation

Thread the conversation_id from any prior response back in the body. The gateway reuses the same runtime session under the hood.

curl -X POST https://agents.example.com/v1/chat/default/general \
  -H 'Authorization: Bearer ao_prod_abcd...' \
  -H 'Content-Type: application/json' \
  -d '{
        "message": "What is my name?",
        "conversation_id": "conv_abcd1234"
      }'

Resume an In-Flight Run

curl -N "https://agents.example.com/v1/chat/default/general/runs/prun_abcd1234/stream" \
  -H 'Authorization: Bearer ao_prod_abcd...'

runs/{id} returns 202 Accepted while the run is still dispatching or running, then the terminal payload once durable.

Step 6 — Update or Disable a Published Agent

PATCH /api/profiles/{name}/published accepts any subset of the published knobs plus enabled. Operators can toggle tool-event streaming on an already-published agent with exposeToolEvents. Setting enabled: false is a fast kill switch that survives without losing history.

curl -X PATCH https://conductor.example.com/api/profiles/general/published \
  -H 'Authorization: Bearer ao_...' \
  -H 'Content-Type: application/json' \
  -d '{"rateLimitRpm": 30, "exposeToolEvents": true, "enabled": true}'

Full unpublish is DELETE /api/profiles/{name}/published. The row is soft-deleted with unpublished_at so the slug becomes immediately reusable for a different profile.

Step 7 — Revoke or Rotate Keys

Revoke One Key

curl -X DELETE https://conductor.example.com/api/profiles/general/keys/key_abcd1234 \
  -H 'Authorization: Bearer ao_...'

The gateway returns 401 unauthorized on the very next request that uses the revoked bearer.

Rotate the Bearer Without Downtime

Issue a new key
Roll the new token out to every client
Revoke the old key

The two keys are accepted in parallel; revoke only after every client carries the new bearer.

Rotating the Signing Key

The gateway-to-conductor HMAC is a shared secret. Rotate by overlapping the previous and current keys on both sides.

Generate a new base64 key
Set CHAT_GATEWAY_SIGNING_KEY_PREVIOUS to the current key on conductor and gateway; set CHAT_GATEWAY_SIGNING_KEY_CURRENT to the new value
Roll restart both services
After at least one nonce window (60 s), remove CHAT_GATEWAY_SIGNING_KEY_PREVIOUS and roll restart again

Mismatched keys produce 502 upstream at the gateway and signature_invalid logs on the conductor’s internal listener.

Rotating the API Key Pepper

The pepper is the HMAC key over every minted bearer hash. Rotating it invalidates every existing key — treat it as a security incident:

Issue new keys to every client first
Update the pepper on conductor and gateway
Revoke the old keys

There is no overlap window for the pepper. A future enhancement may add AGENT_API_KEY_PEPPER_PREVIOUS.

Observability

The chat gateway emits structured JSON logs with service=chat-gateway. Key events:

Log	Meaning
`chat-gateway.ready`	Boot complete; includes `conductor_internal_url` and `rate_limit_backend`
`auth.lookup_failed`	Postgres lookup error during key validation
`chat.resolve_conv_failed`	`conversation_id` missing or cross-agent
`chat.start_watcher_failed`	Conductor internal `POST /api/runs` returned non-2xx
`ingress.flush_failed`	A gateway ingress-meter flush failed; the affected interval’s request count is dropped
`crash.recovery.sweep`	Counts orphan `gateway_runs` rows swept on boot; rows without an internal run are finalized as `lost`

Accepted public chat requests are also flushed into usage_records as the ingress meter. Operators can read the tenant-wide total and top published agents from GET /api/usage, or the scoped agent-detail series from GET /api/profiles/{name}/metrics. Prometheus metrics are exposed on /metrics:

Metric	Type	Description
`chat_gateway_requests_total{route,status}`	Counter	Public requests by route and HTTP status
`chat_gateway_request_duration_seconds{route}`	Histogram	End-to-end request duration
`chat_gateway_watcher_active`	Gauge	Watchers currently in-flight
`chat_gateway_run_terminal_total{status}`	Counter	Terminal `done` and `error` events

Common Smoke Test

After deploy, this five-command sequence proves the surface end-to-end:

# 1. Healthcheck
curl -s https://agents.example.com/healthz

# 2. Publish
curl -s -X POST https://conductor.example.com/api/profiles/general/publish \
  -H 'Authorization: Bearer ao_...' -H 'Content-Type: application/json' -d '{}'

# 3. Mint a key
TOKEN=$(curl -s -X POST https://conductor.example.com/api/profiles/general/keys \
  -H 'Authorization: Bearer ao_...' -H 'Content-Type: application/json' \
  -d '{"label":"smoke"}' | jq -r .token)

# 4. Sync chat
curl -s -X POST https://agents.example.com/v1/chat/default/general \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"message":"hello"}'

# 5. Stream chat
curl -N -X POST https://agents.example.com/v1/chat/default/general/stream \
  -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"message":"stream it"}'

See Chat Gateway API for full request and response schemas, and Conductor publish endpoints for every conductor route this guide touches.

Get Started

Core Concepts

Guides

Publishing an Agent

Overview

Prerequisites

Step 1 — Configure Conductor for the Internal Listener

Postgres Role Requirement

Step 2 — Deploy the Chat Gateway

Step 3 — Publish a Profile

Step 4 — Mint an API Key

Step 5 — Call the Public Endpoint

Sync Chat

Streaming Chat

Continuing a Conversation

Resume an In-Flight Run

Step 6 — Update or Disable a Published Agent

Step 7 — Revoke or Rotate Keys

Revoke One Key

Rotate the Bearer Without Downtime

Rotating the Signing Key

Rotating the API Key Pepper

Observability

Common Smoke Test

​Overview

​Prerequisites

​Step 1 — Configure Conductor for the Internal Listener

​Postgres Role Requirement

​Step 2 — Deploy the Chat Gateway

​Step 3 — Publish a Profile

​Step 4 — Mint an API Key

​Step 5 — Call the Public Endpoint

​Sync Chat

​Streaming Chat

​Continuing a Conversation

​Resume an In-Flight Run

​Step 6 — Update or Disable a Published Agent

​Step 7 — Revoke or Rotate Keys

​Revoke One Key

​Rotate the Bearer Without Downtime

​Rotating the Signing Key

​Rotating the API Key Pepper

​Observability

​Common Smoke Test

Overview

Prerequisites

Step 1 — Configure Conductor for the Internal Listener

Postgres Role Requirement

Step 2 — Deploy the Chat Gateway

Step 3 — Publish a Profile

Step 4 — Mint an API Key

Step 5 — Call the Public Endpoint

Sync Chat

Streaming Chat

Continuing a Conversation

Resume an In-Flight Run

Step 6 — Update or Disable a Published Agent

Step 7 — Revoke or Rotate Keys

Revoke One Key

Rotate the Bearer Without Downtime

Rotating the Signing Key

Rotating the API Key Pepper

Observability

Common Smoke Test