Skip to content
Enterprise

Enterprise setup

Upgrade, generate your credentials, download the image, add your settings, and run your agent.

Set up your agent

Use your own GitHub App to connect repositories to your nodes. The Reelay Agent scans and analyzes them in your infrastructure; Reelay Cloud never receives your repository names, branches, source code, or GitHub credentials.

Follow the setup steps below. Run the terminal commands on a host with Docker installed. Your GitHub and model credentials stay on that host.

1. Upgrade to Enterprise

Open Settings → Payments in your workspace and request an Enterprise upgrade. Once the plan is active, open Agents to generate credentials and download the private image.

Already on Enterprise? Go straight to step 2.

2. Generate your credentials

Open Agents and generate these two credentials. Copy and save the agent token when it appears — you won't be able to see it again, only its prefix.

Use a separate token for each environment. You can have up to 5 active tokens. Deleting a token stops its deployments from authenticating immediately.

  • Agent token: lets the running agent connect to Reelay. Add it to your settings as REELAY_AGENT_TOKEN.
  • Registry password: lets Docker download the image. It is valid for 12 hours and is separate from the agent token.

3. Download the image

In Agents, pick the image version (the workspace default is preselected), generate a registry password, then copy the full log-in-and-download command. It logs in via --password-stdin and pulls your image in one step.

Run it in a terminal with Docker installed. After you see Login Succeeded and the pull completes, continue to step 4.

Copy this exact command from Agents
printf '%s\n' <password-from-Agents> | docker login <registry-from-Agents> --username <username-from-Agents> --password-stdin && docker pull <private-image-uri-from-Agents>

4. Create your GitHub App

Create an app in the GitHub account or organization that owns your repositories. Keep reelay-agent.env and github-app.pem together in a deployment folder. Install the app on the repositories you want to link; the agent lists only repositories its GitHub App can access.

  1. Open GitHub Settings → Developer settings → GitHub Apps → New GitHub App. Give it a name and homepage URL.

  2. Under repository permissions, set Contents to Read-only and Pull requests to Read-only. Leave other permissions at No access unless GitHub requires them. Create the app, then install it on the repositories you want to show in the dashboard.

  3. Note the App ID, generate a private key, and save the downloaded PEM file as github-app.pem.

  4. Grant access only to repositories the agent should scan. You can expand the installation later when you need to link more repositories.

Create deployment folder
mkdir -p reelay-agent-deployment
cd reelay-agent-deployment

5. Add your secrets and settings

Save the environment template in your deployment folder and replace every placeholder before starting the agent. Once it connects, use your GitHub App to link repositories from the dashboard.

The dashboard repository flow requires the agent's public HTTPS endpoint and a trusted certificate. Bundled Caddy obtains and renews certificates automatically. Plain HTTP mode can serve SDK ingestion on a trusted network, but it cannot register an agent repository route. The Reelay control-plane connection always uses HTTPS.

Environment file template

Save this as reelay-agent.env in your deployment folder. Set REELAY_GITHUB_APP_ID to the App ID from step 4 — the start command loads the real multiline PEM from github-app.pem, so don't paste the key into the env file. The control-plane URL is fixed by the image. Set REELAY_DASHBOARD_ORIGIN to the exact URL of your dashboard. Use HTTPS and REELAY_INGEST_DOMAIN for dashboard repository linking.

Set REELAY_MONGO_URL to a database reachable from inside the container, not localhost. Run chmod 600 reelay-agent.env github-app.pem and keep this file outside source control; use your platform's secret manager in production.

reelay-agent.env
# Save as reelay-agent.env. Replace every replace-with value.
# Docker env files use unquoted KEY=value lines.
REELAY_AGENT_TOKEN=replace-with-agent-token-from-agent-tokens
# Use a database reachable from inside the container, not localhost.
REELAY_MONGO_URL=replace-with-your-mongodb-connection-string
# Exactly openai or anthropic.
REELAY_LLM_API_TYPE=openai
REELAY_LLM_API_KEY=replace-with-your-llm-api-key
REELAY_LLM_MODEL=replace-with-your-llm-model
REELAY_LLM_BASE_URL=https://api.openai.com/v1
# HTTP base URLs are accepted only when REELAY_HTTPS_ONLY=false.
REELAY_GITHUB_APP_ID=replace-with-your-github-app-id
# The start command loads the real multiline PEM from github-app.pem.
# Default true. Set false to serve HTTP on port 80 without certificates.
REELAY_HTTPS_ONLY=true
# Public hostname pointing directly to this server. Caddy manages certificates.
# Required only when REELAY_HTTPS_ONLY=true (default). Omit it for HTTP mode.
# SDKs must use https://your-hostname by default, or http://your-hostname when
# REELAY_HTTPS_ONLY=false. HTTPS-mode HTTP ingestion returns 403 Forbidden.
# Publish ports 443 (HTTPS) and 80 (certificate validation only); HTTP mode
# serves port 80.
REELAY_INGEST_DOMAIN=replace-with-your-public-ingest-hostname
# Exact dashboard origin allowed to call this agent's repository APIs.
REELAY_DASHBOARD_ORIGIN=https://app.usereelay.com
# Comma-separated actual SDK source IPs/CIDRs; forwarded headers are not trusted.
# Leaving this empty denies all incoming SDK traffic.
REELAY_ALLOWED_IPS=replace-with-allowed-source-ips-or-cidrs
# OpenGrep, Trivy, and OpenCodeReview are bundled in the agent image.
# No scanner URLs, shared keys, Docker socket, or scanner services are needed.
# Link repositories to nodes in the dashboard after the agent connects.
HTTPS and network settings
  • HTTPS is the default. Set REELAY_INGEST_DOMAIN to a public hostname and point its DNS A/AAAA records directly to your server. The bundled Caddy obtains and renews trusted certificates automatically.
  • To serve plain HTTP on a trusted network instead, set REELAY_HTTPS_ONLY=false and omit REELAY_INGEST_DOMAIN. The agent serves port 80 (container port 8080) with no certificates, and REELAY_LLM_BASE_URL may use HTTP. The Reelay control-plane connection still uses HTTPS. Use HTTP only behind a TLS-terminating proxy or on a trusted network — SDK tokens, webhook contents, and model keys are unencrypted.
  • Set REELAY_ALLOWED_IPS to comma-separated actual SDK source IPs/CIDRs; forwarded headers are not trusted. Blank blocks all traffic; * allows all.
  • For HTTPS mode, open public TCP ports 80 and 443. Port 443 accepts HTTPS SDK traffic; port 80 serves Caddy's certificate-validation challenges only. Other HTTP requests return 403 Forbidden without redirecting to HTTPS. HTTP mode serves port 80 only.
  • Keep the reelay-caddy-data volume across restarts; it contains private certificate keys. Do not delete it when updating the container.
  • Allow outbound HTTPS to Let's Encrypt, Reelay, GitHub, your model provider, and Trivy database registries, plus DNS resolution.
  • Keep MongoDB reachable from the container. Docker Compose in the agent source includes MongoDB for a database-backed deployment.
  • Provide at least 6 GiB of container memory and writable temporary storage for bundled scans.

6. Run your agent

Start the container from your deployment folder, then check the logs for Handshake successful. Wait about 30 seconds, then press Refresh in Agents to see it under Connected agents.

In HTTPS mode, certificate issuance may still be pending; verify your HTTPS endpoint with normal certificate checking before connecting SDKs.

Start agent (copy the exact command from Agents)
docker run -d --name reelay-agent \
--restart unless-stopped --init \
--cap-drop ALL --pids-limit 512 \
--memory 6g --cpus 2 \
--security-opt no-new-privileges:true \
--read-only --tmpfs /tmp:rw,nosuid,exec,size=4g \
--env-file ./reelay-agent.env \
-e "REELAY_GITHUB_APP_PRIVATE_KEY_PEM=$(cat ./github-app.pem)" \
-p 443:8443 -p 80:8080 \
--mount type=volume,src=reelay-caddy-data,dst=/var/lib/reelay/caddy \
<private-image-uri-from-Agents>
View logs
docker logs --tail 100 -f reelay-agent
Verify HTTPS
curl -v https://ingest.example.com/
Verify HTTP rejection (HTTPS mode, expect 403)
curl -i http://ingest.example.com/api/ingest/errors
Verify HTTP mode (REELAY_HTTPS_ONLY=false)
curl -i http://your-hostname/api/ingest/errors
Connect your SDKs

Use your agent's endpoint without a port suffix (https://your-hostname by default, or http://your-hostname when REELAY_HTTPS_ONLY=false), each SDK node's own node ID, and that node's ingest key from Nodes. The SDK ingest key is separate from your agent token. In HTTPS mode, HTTP ingestion requests return 403 Forbidden and are never processed or stored.

Browser SDK example
import * as Reelay from "@usereelay/browser";
Reelay.init({
endpoint: "https://ingest.example.com",
nodeId: "<workspace-node-id>",
ingestKey: "<node-ingest-key>",
});
Agent not connecting?
ProblemWhat to check
Image download deniedGenerate a fresh registry password, log in again, and use the exact image address. Passwords expire after 12 hours.
Handshake failsCheck your Enterprise plan, agent token, control-plane URL (https://api.usereelay.com), and outbound HTTPS.
Agent fails at startupCheck placeholders, a container-reachable MongoDB (not localhost), the github-app.pem key file, REELAY_ALLOWED_IPS, and REELAY_INGEST_DOMAIN when REELAY_HTTPS_ONLY=true.
No SDK eventsCheck the endpoint for your mode (https://your-hostname with no :8443, or http://your-hostname when REELAY_HTTPS_ONLY=false), TLS certificate in HTTPS mode, allowed IPs, node ID, and ingest key. In HTTPS mode, HTTP returns 403 by design.
Scan failsCheck repository access and that the GitHub App is installed on the target repositories. Scanners are bundled — no scanner URLs or keys are needed.
Analysis failsCheck the model API key, model access, gateway URL, and outbound connectivity. Bedrock requires both a gateway base URL and a model.

After setup

Send a test SDK event, run a scan, and try an analysis to check the complete deployment.

Updates and token rotation

To update the image, generate a new registry password, download the new version, and redeploy. Pin a version or digest when you need reproducible deployments. Keep the reelay-caddy-data volume so certificates survive the update.

To rotate an agent token, generate a second token, update your deployment, and verify it connects. Then revoke the old token. You can have up to 5 active tokens — use a separate token per environment. Revoking a token stops authentication immediately; downloaded images and local data remain on your host.

Monitor heartbeats, scanner failures, model usage, and database health. Back up MongoDB. The agent needs an active Enterprise plan and access to the Reelay control plane.

Where data and credentials go
DestinationData
Your infrastructureGitHub and model credentials, repository names and branches, source files, SDK payloads, scan findings, analysis results, and MongoDB.
ReelayAccount and agent connection metadata, job status, and heartbeats. No repository names, branches, source code, or GitHub credentials.
Your configured servicesGitHub supplies source. Your model provider receives the context needed for analysis and bills your account.
Model providers and suggested fixes

The default provider mode is openai. You can override the model with REELAY_LLM_MODEL and a compatible gateway with REELAY_LLM_BASE_URL (omit /chat/completions or /messages). The gateway must use HTTPS unless REELAY_HTTPS_ONLY=false, which also allows HTTP model API URLs. Bedrock requires an OpenAI-compatible gateway and an explicit model ID.

Choose a model your account can access and verify it with a test analysis. Reports and suggested patches are saved locally. Analysis does not automatically resolve an incident, apply a patch, publish a pull request, or deploy changes.