Relay stores a route for every deploy lane.
You can run Relay in direct host-port mode or let Relay manage host routing through its built-in Caddy global proxy. The dashboard and CLI still use the preview_url field stored on the deploy record, even when the lane is production, staging, or dev, so it helps to understand how routes, signed access, expiry, and promotion connect.
Port mode: http://127.0.0.1:3005
Preview: https://demo-preview-f4a91c2d.relay.example.com
Dev host: https://demo-dev-a1b2c3d4.relay.example.com
Stage host: https://demo-staging.relay.example.comThe simplest setup maps a host port directly to the app container.
This is the easiest mode to start with locally. The agent launches the app container with a host port mapping and stores a route like http://127.0.0.1:<port>. Any lane can use port mode when you want direct ownership of the host port.
relay deploy --host-port 3005 --streamIf RELAY_BASE_DOMAIN is set, the agent can derive lane hostnames automatically.
In host mode, Relay runs a per-app edge proxy for the app slot and a global Caddy proxy for public domains. staging gets a stable <app>-staging.<base-domain> host, while dev and preview can both generate random aliases that stay attached to that lane until you change the public host explicitly.
Set RELAY_BASE_DOMAIN=relay.example.com on the agent.
Optional but recommended: set RELAY_DASHBOARD_HOST=admin.relay.example.com so the Relay dashboard has its own hostname.
Make sure DNS points both the dashboard host and app hosts at the same server IP.
Relay stores the derived public host on app state and keeps the resulting route on the deploy record.
RELAY_BASE_DOMAIN=relay.example.com
preview: demo-preview-f4a91c2d.relay.example.com
staging: demo-staging.relay.example.com
dev: demo-dev-a1b2c3d4.relay.example.comRouting now carries access, expiry, and promotion behavior too.
A lane route is no longer just a hostname. dev and preview can auto-expire after the retention window, signed-link lanes can mint temporary share URLs, and staging can promote the exact staged image into production while keeping rollback attached to the target lane.
These lanes refresh their expiry when you deploy, start, or restart them. Once the retention window passes, Relay stops the lane and records the event in audit.
If access_policy is signed-link, the dashboard can mint a temporary share URL that appends relay_exp and relay_sig before the request reaches the app.
Promotion moves the staged image into the target lane rather than rebuilding from scratch, which keeps rollback tied to the exact image that was validated earlier.
When user accounts are enabled, non-owner requests to promote staging into prod pause for owner approval before the production deploy is queued.
preview alias: https://demo-preview-f4a91c2d.relay.example.com
signed link: https://demo-preview-f4a91c2d.relay.example.com?relay_exp=...&relay_sig=...
expiry worker: lane.expire env=preview branch=main
promotion: staging/main -> prod/mainHost mode uses blue-green slots behind the edge proxy.
The agent alternates between blue and green containers, points the edge proxy at the newly ready slot, and keeps the previous slot alive for a short drain window. traffic_mode controls how the proxy treats clients during that window, and access_policy controls who is allowed through at all.
Stored on app state so the agent knows which slot is currently live.
All requests move to the new active slot as soon as the proxy is reloaded.
The edge proxy sets a relay_slot cookie and can keep a browser pinned to a specific slot for the duration of the standby window.
public, relay-login, signed-link, or ip-allowlist are enforced before the request reaches the current slot.
signed-link lanes can mint a temporary share URL from the dashboard instead of asking an operator to handcraft relay_exp and relay_sig values.
The old slot is removed only after RELAY_ROLLOUT_DRAIN_SECONDS elapses.
{
"app": "demo",
"env": "dev",
"branch": "main",
"mode": "traefik",
"traffic_mode": "session",
"public_host": "demo-dev-a1b2c3d4.relay.example.com",
"access_policy": "relay-login",
"service_port": 3000
}Keep the dashboard hostname separate from app hostnames.
Relay itself serves the dashboard root on its own host. If you point an app at the same hostname, requests can resolve to the dashboard instead of the app. Give the dashboard and each app separate hosts so session cookies and route ownership stay legible.
Use a dedicated admin host such as admin.relay.example.com.
Use a different host or let Relay derive lane hosts such as <app>-preview-<token>.<base-domain>, <app>-staging.<base-domain>, or <app>-dev-<token>.<base-domain>.
If nginx is still bound to :80 or :443, it will intercept requests before Relay's Caddy proxy can route them. Stop and disable it.
Relay binds :80 on startup and serves ACME HTTP-01 challenge tokens directly. Set RELAY_ACME_EMAIL so Let's Encrypt can issue and renew certs automatically.
The admin rejects saving a public_host that matches the configured dashboard host.
Dashboard: https://admin.relay.example.com
Preview: https://site-preview-f4a91c2d.relay.example.com
Staging: https://site-staging.relay.example.com
Dev: https://site-dev-a1b2c3d4.relay.example.comVerify DNS and host routing with curl before opening a browser.
The quickest way to separate DNS problems from proxy problems is to resolve the host manually and inspect the response headers. Test the dashboard host and the app host independently, then confirm whether the edge policy is returning the expected 401 or 403.
Confirm both names resolve to the server IP with nslookup or dig.
Use curl --resolve against the dashboard host and the app host before relying on browser cache or DNS propagation.
If the response still says Server: nginx, your old front proxy is still in the path.
If the app host returns 401 or 403, the edge policy is active. signed-link lanes should return 401 until relay_exp and relay_sig are present. If it redirects to /dashboard/, the app host still collides with the dashboard host or an old proxy rule.
curl -I --resolve admin.relay.example.com:443:185.27.135.235 https://admin.relay.example.com
curl -I --resolve site-staging.relay.example.com:443:185.27.135.235 https://site-staging.relay.example.comLane URLs are part of the deploy history, not a front-end guess.
The dashboard shows a Visit link because the server stores a preview_url on each deploy once rollout completes. Deploy history also carries the routing shape that was live at the time through app state fields like mode, public_host, host_port, active_slot, traffic_mode, and access_policy.
Stores the preview_url for the specific deployment.
Stores host mode, host port, service port, public host, active slot, traffic mode, access policy, and expiry data for the lane.
Prints the stored route when the deploy reaches ready state.
Render the route as a clickable link when present and expose signed-link generation or promotion controls when the lane policy allows it.
lane URL: https://site-staging.relay.example.com
deploy success. image=relay/site-demo:staging-main-...