Self-Hosted Egress Requirements

Use this page when a self-hosted Runlayer deployment sits behind an egress firewall, SWG, or URL allowlist. Allowlists for managed devices (laptops, MDM) are separate — see Network & Firewall Requirements (browser soft hosts such as models.dev live there). Unless noted otherwise, allow HTTPS / TCP 443 from the deployment VPC (backend, worker, and related tasks/pods — or ToolGuard EC2 where called out). Replace <region> with the deployment Region (for example us-east-1).

Prefer hostname allowlists. Ubuntu mirrors, NVIDIA package CDNs, Docker Hub, and ECR Public use CDNs or redirects; IP allowlists break easily. For AWS APIs you can use VPC endpoints instead of public internet allowlisting.

Core platform (always)

Required for login, catalog sync, image pull, and connector OAuth from the backend and worker.

Hostname	Purpose
`api.workos.com`	SSO, SCIM, and WorkOS user/session APIs
`<slug>.authkit.app`	WorkOS AuthKit issuer for agent run / M2M token minting — see AuthKit
`mcp-catalog.prod.runlayer.com`	MCP catalog API — set `mcp_catalog_api_url` explicitly; see Catalog URL
`oauth.runlayer.com`	Shared OAuth Broker when `oauth_broker_url` points at the hosted broker
`public.ecr.aws`	Default module image registry (`public.ecr.aws/anysource/…`)
`api.ecr-public.<region>.amazonaws.com`	ECR Public API (auth for `public.ecr.aws` pulls)
`088332244652.dkr.ecr.<region>.amazonaws.com`	CustomerDistribution private ECR — agent sandbox, ToolGuard, hooks, telemetry-proxy defaults
`*.dkr.ecr.<region>.amazonaws.com`	Pull from private / mirrored ECR (including CustomerDistribution)
`ecr.<region>.amazonaws.com`	ECR API (auth/token) for private registries
`logs.<region>.amazonaws.com`	CloudWatch Logs
`monitoring.<region>.amazonaws.com`	CloudWatch metrics
`secretsmanager.<region>.amazonaws.com`	Secrets Manager (module-managed app secrets)
`sts.<region>.amazonaws.com`	STS (task role / assume-role)
`s3.<region>.amazonaws.com` and `s3.amazonaws.com`	S3 for audit archive, session payloads, and related buckets

oauth_broker_url is not WorkOS. WorkOS (SSO/SCIM) always uses api.workos.com + AuthKit. The broker is only for connector OAuth vendor redirects. If you override ecr_repositories to your own private registry, you still need that registry’s host (and may drop public.ecr.aws / ECR Public). CustomerDistribution (088332244652) remains required for any service still using the module’s default private-ECR image URIs.

Catalog URL

Set mcp_catalog_api_url = "https://mcp-catalog.prod.runlayer.com" for production self-hosted. The application code default is https://mcp-catalog.staging.runlayer.com — an empty or omitted Terraform URL falls through to staging and typically returns 401 with a production catalog API key. Catalog auth uses header x-runlayer-api-key (exactly 32 characters); prod and staging keys differ.

Binary package CDN

When runlayer_download_token is set (CLI / AI Watch / extension binary discovery):

Hostname	Purpose
`downloads.runlayer.com`	Release manifests and binaries (`runlayer_downloads_base_url` default)

Empty token disables discovery; no egress needed for this host from the VPC in that case. Managed devices still need downloads.runlayer.com for the browser extension and Terraform provider — see Network & Firewall Requirements.

AuthKit domain

WorkOS assigns a fixed AuthKit host per WorkOS environment (shape: <random-slug>.authkit.app). The slug does not rotate day to day.

Stable for a given auth_client_id / WorkOS environment.
Different if staging and production use different WorkOS environments (different client IDs) — each gets its own *.authkit.app host (production may instead use a custom AuthKit domain).
Same AuthKit host if staging and production share one WorkOS environment and client ID (both redirect URIs registered on that client).

The hostname is not a Terraform input; the backend discovers it from WorkOS. Allow the exact host from firewall logs, or *.authkit.app if your proxy supports wildcards. Login vs agent auth: blocking api.workos.com typically shows a long hang (often ~10s) then redirect to /?error=ApiError&error_url=%2Fapi%2Fv1%2Fusers%2Fme&error_status=401 even though WorkOS may have already authenticated the browser. Blocking AuthKit often surfaces later as Failed to generate authentication token for agent run while interactive login already works.

Agents and Runlayer Assistant

When Agents are enabled (enable_runlayer_agents on ECS, or equivalent on EKS):

Hostname	Purpose
`bedrock-runtime.<region>.amazonaws.com`	Bedrock model invoke (Runlayer Assistant always uses Bedrock)
`bedrock.<region>.amazonaws.com`	Bedrock control plane / model access
`bedrock-agentcore.<region>.amazonaws.com`	AgentCore runtime APIs (when AgentCore is enabled)
`lambda.<region>.amazonaws.com`	Agent sandbox Lambda invoke (when Lambda sandbox is enabled)

enable_bedrock_anthropic_models only gates Bedrock Anthropic models for custom agent runs. The managed Runlayer Assistant uses Bedrock regardless of that flag and ignores Settings → AI Providers. Default Assistant model: us.anthropic.claude-opus-4-6-v1. Account-level Anthropic access for a different Claude model does not satisfy this. Module v28.1.x+ auto-submits Anthropic’s use-case form via bedrock_auto_model_access (default true) and attaches the required model-access IAM actions to the task role — for self-managed installs override bedrock_model_access_* before first submit. See troubleshooting.

AgentCore with WAF IP allowlisting

If the public ALB uses WAF IP allowlisting, AgentCore PUBLIC mode cannot reliably call APP_URL (no stable egress IPs to put on the allowlist). Use AgentCore VPC mode with PrivateLink so callbacks stay private:

enable_runlayer_agents            = true
enable_runlayer_agentcore_runtime = true
enable_privatelink                = true
runlayer_agentcore_network_mode   = "VPC"
# plus consumer VPC / subnet inputs — see Terraform guide

Same-VPC consumer subnets are fine when they already have NAT/HTTPS egress. Details: ECS + Terraform and Terraform ECS inputs.

ToolGuard (GPU) bootstrap

When enable_runlayer_tool_guard is on, ToolGuard EC2 userdata installs NVIDIA GRID, Docker, the NVIDIA container toolkit, CloudWatch agent, and the ECS agent before the instance registers with the capacity provider. The inference image itself is self-contained after bootstrap; the outbound calls below are for host setup, not model downloads at request time. If those hosts are blocked, ECS reports TaskFailedToStart: EMPTY CAPACITY PROVIDER while ASG instances look healthy — they never join the cluster. Also set runlayer_tool_guard_gpu_resource_value = "ALL" (module default) on g6f.* fractional-GPU instances. Using "1" can fail later with INTEGER_GPU_ON_FRACTIONAL_INSTANCE after capacity registration succeeds. Confirm GPU quota and g6f.large (or your configured type) availability in the AZs used by your private subnets.

Hostname	Purpose
`archive.ubuntu.com`	`apt` packages (kernel headers / build tools for GRID)
`security.ubuntu.com`	Ubuntu security updates
`awscli.amazonaws.com`	AWS CLI installer (downloads GRID from S3)
`ec2-linux-nvidia-drivers.s3.amazonaws.com`	NVIDIA GRID driver object
`s3.<region>.amazonaws.com`	GRID download + ECS agent package (`amazon-ecs-agent-<region>/…`)
`s3.amazonaws.com`	CloudWatch agent package (global S3 URL in userdata — expected)
`download.docker.com`	Docker CE GPG + packages
`nvidia.github.io`	NVIDIA Container Toolkit apt repo / GPG
`ecs.<region>.amazonaws.com`	ECS control plane after the agent starts
`ecr.<region>.amazonaws.com` / `*.dkr.ecr.<region>.amazonaws.com`	ToolGuard image pull (often CustomerDistribution)
`logs.<region>.amazonaws.com`	Task / agent logs

Optional (GPU smoke test only; userdata continues on failure):

Hostname	Purpose
`registry-1.docker.io`	Docker Hub
`auth.docker.io`	Docker Hub auth

Feature-conditional (backend / worker)

Allow only the features you enable. Connector and MCP upstreams are unbounded — derive hosts from each connector’s URL and OAuth authorization endpoint.

Hostname	When	Purpose
`api.openai.com`	Org OpenAI key / non-Bedrock agents	OpenAI API
`api.anthropic.com`	Org Anthropic key / compliance paths	Anthropic API
`api.chatgpt.com`	OpenAI compliance import	Compliance sync
`slack.com`, `api.slack.com`, `files.slack.com`	Slack integration	Agents-in-Slack, OAuth, file download
`codeload.github.com` (and `github.com` as needed)	Skills import from GitHub	`fetch_skills_from_github`
Customer SMTP host (e.g. `smtp.resend.com:587`)	Email notifications	Outbound mail
`login.microsoftonline.com`	Agent365 / Microsoft OAuth	Microsoft identity
OAuth vendor hosts (GitHub, Asana, Box, Datadog, Ramp, …)	Self-hosted broker or connectors that call vendors from the VPC	Per-connector OAuth / token exchange
Each MCP `server.url` host	Installed connectors	Proxy tool calls to upstream SaaS
`kinesis.<region>.amazonaws.com`, `dynamodb.<region>.amazonaws.com`	Audit log Kinesis path	Stream publish / checkpoint
`ecs.<region>.amazonaws.com`, `ecr.<region>.amazonaws.com`	Runlayer Deploy	Deployment control plane / logs
Customer OTEL / central OTLP endpoint	OTEL sidecar dual-export	Metrics / traces export
Google Cloud APIs	GCP SIEM export	SIEM sink

Optional monitoring (Sentry)

Only if Runlayer Sentry / Relay is enabled. Module default Relay upstream is https://o4509836808028160.ingest.us.sentry.io. Allow that exact host (or your DSN’s ingest host), or turn Sentry off / point it at your own org so you do not need Runlayer’s ingest egress. Browser Sentry (frontend_sentry_dsn) is a managed-device egress concern — see Network & Firewall Requirements. To use your own Sentry (or disable Runlayer monitoring egress):

# Backend / workers
sentry_dsn = "https://<key>@<your-org>.ingest.sentry.io/<project-id>"

# Do not use Runlayer Relay credentials against a foreign org
sentry_relay_enabled = false

# Browser (optional)
frontend_sentry_dsn = "https://<public-key>@<your-org>.ingest.sentry.io/<project-id>"

# Agent sandbox (optional, separate)
runlayer_agent_sandbox_sentry_dsn = "https://..."

# Optional: also send tool-call / security audit events
# sentry_audit_events_enabled = true

Or leave DSNs empty and set sentry_relay_enabled = false to skip Sentry egress entirely. See Sentry Relay.

AWS VPC endpoints

With enable_vpc_endpoints = true and a module-managed VPC (existing_vpc_id = null), the ECS module creates:

Endpoint	Always / when
S3 (gateway)	Always
ECR API + ECR DKR (interface)	Always
CloudWatch Logs (interface)	Always
Secrets Manager (interface)	When tunnel router is enabled
DynamoDB (gateway)	When `enable_audit_log_kinesis`
Kinesis Streams (interface)	When `enable_audit_log_kinesis`

It does not currently create STS, Monitoring, ECS, or Bedrock endpoints — allow those on the public internet (or add your own endpoints). Non-AWS hosts (api.workos.com, *.authkit.app, mcp-catalog.prod.runlayer.com, oauth.runlayer.com, public.ecr.aws, Ubuntu, Docker, NVIDIA) still need hostname allowlisting. ECR Public (public.ecr.aws) is not covered by private ECR VPC endpoints.

Symptom → missing egress

Symptom	Likely missing host(s)
Login hangs ~10s, then `/?error=ApiError` on `GET /users/me` (401) after WorkOS browser success	`api.workos.com`
`Failed to generate authentication token for agent run`	`<slug>.authkit.app`
Catalog / connector sync failures or catalog 401	`mcp-catalog.prod.runlayer.com` and/or wrong URL/key (staging default)
Brokered connector OAuth broken	`oauth.runlayer.com`
ECS tasks fail to pull images	`public.ecr.aws` / ECR Public API, or CustomerDistribution `088332244652.dkr.ecr…`
Binary / CLI release discovery fails	`downloads.runlayer.com` (when download token set)
ToolGuard `EMPTY CAPACITY PROVIDER`, EC2 up, 0 container instances	ToolGuard bootstrap table (often Ubuntu + GRID S3 / Docker / NVIDIA)
ToolGuard tasks place then fail `INTEGER_GPU_ON_FRACTIONAL_INSTANCE`	Set `runlayer_tool_guard_gpu_resource_value = "ALL"`
Assistant / Bedrock invoke failures	`bedrock-runtime.<region>.amazonaws.com` / `bedrock.<region>.amazonaws.com` — or Anthropic model access (not egress); see troubleshooting
`does not have access to the Anthropic model yet` / use-case form errors	Not an egress miss — Bedrock model access / task-role IAM / specific model id
Model picker hover cards empty (UI only)	Browser SWG blocking `models.dev` — see Network & Firewall
Broken connector icons (UI only)	Browser SWG blocking `img.logo.dev`

Network & Firewall Requirements — managed devices, browser soft hosts, inbound WAF
ECS + Terraform
Terraform ECS inputs
EKS + Terraform
Networking
OAuth Broker

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Self-Hosted Egress Requirements

Core platform (always)

Catalog URL

Binary package CDN

AuthKit domain

Agents and Runlayer Assistant

AgentCore with WAF IP allowlisting

ToolGuard (GPU) bootstrap

Feature-conditional (backend / worker)

Optional monitoring (Sentry)

AWS VPC endpoints

Symptom → missing egress

​Core platform (always)

​Catalog URL

​Binary package CDN

​AuthKit domain

​Agents and Runlayer Assistant

​AgentCore with WAF IP allowlisting

​ToolGuard (GPU) bootstrap

​Feature-conditional (backend / worker)

​Optional monitoring (Sentry)

​AWS VPC endpoints

​Symptom → missing egress

​Related pages

Core platform (always)

Catalog URL

Binary package CDN

AuthKit domain

Agents and Runlayer Assistant

AgentCore with WAF IP allowlisting

ToolGuard (GPU) bootstrap

Feature-conditional (backend / worker)

Optional monitoring (Sentry)

AWS VPC endpoints

Symptom → missing egress

Related pages