Relay BYO deployment example

This walkthrough self-hosts ArcFlow Relay beside your own arcflow-server using Docker Compose. Browser clients use site tokens and Origin checks identical to managed Relay.

Primary example: Relay BYO deployment walkthrough.

What this example demonstrates

Bring-your-own (BYO) Relay lets operators run the browser proxy in their VPC while upstream execution stays on arcflow-server. Site configuration (allowed origins, rate limits, upstream runtime keys) loads from ARCFLOW_RELAY_SITES_JSON.

Prerequisites

Step 1: Start upstream server

From repository root:

docker compose -f docker/docker-compose.server.yml up -d
curl -sf http://localhost:8080/ready

Step 2: Configure Relay sites JSON

Export upstream URL and site definition (from README.md):

export ARCFLOW_UPSTREAM_URL=http://host.docker.internal:8080
export ARCFLOW_RELAY_SITES_JSON='[{
 "id": "s_dev",
 "display_name": "Dev",
 "allowed_origins": ["http://localhost:5173"],
 "rate_limit_rpm": 60,
 "allow_inline": false,
 "default_workflow_name": "chat",
 "kb_namespace": "site-s_dev-kb",
 "upstream_runtime_key": "dev-secret",
 "token": "st_live_devtoken"
}]'

On Linux Docker, replace host.docker.internal with the host gateway IP if needed.

Step 3: Start BYO Relay

cd examples/relay/byo-docker
docker compose -f compose.yml up --build

Verify health:

curl -sf http://localhost:8090/health

Step 4: Point static frontend at BYO Relay

VITE_ARCFLOW_RELAY_URL=http://localhost:8090/v1/sites/s_dev
VITE_ARCFLOW_SITE_TOKEN=st_live_devtoken

Run Static chat widget walkthrough or your own static bundle against port 8090.

Relay routes

Auth: Authorization: Bearer {site_token} plus allowed Origin header on browser requests.

Expected output

Health endpoint returns 200. Browser chat through Relay creates runs on upstream server with site-scoped runtime key. Rate limiting applies per rate_limit_rpm when configured.

Pass criteria:

Trace events you should see

Retrieve via Relay trace route or server admin tools. Expect standard workflow lifecycle events on published workflow runs (WorkflowStarted, StepCompleted, WorkflowCompleted, optional MemoryRetrieved for RAG sites).

Troubleshooting

Related