Network and 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 img.logo.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.

Plan network access before deployment

Both platforms need client HTTPS access to the application, DNS resolution, private database/cache connectivity, and outbound access for authentication, catalog, image pulls, and selected features. For ingress and private topology choices, use ECS networking or Kubernetes prerequisites. The AWS endpoints below apply to ECS and AWS-backed Kubernetes components. On GKE, use the endpoints for the Google Cloud services and image registry you actually configure, plus the shared external service hosts.

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
`distribution.prod.runlayer.com`	Feature flag, entitlement, and licensing configuration
`oauth.runlayer.com`	Shared OAuth Broker when `oauth_broker_url` points at the hosted broker
`088332244652.dkr.ecr.<region>.amazonaws.com`	Default application and optional-service images in Customer Distribution private ECR
`*.dkr.ecr.<region>.amazonaws.com`	Pull from private / mirrored ECR (including CustomerDistribution)
`api.ecr.<region>.amazonaws.com` / `ecr.<region>.amazonaws.com`	ECR API (auth/token) for private registries
`prod-<region>-starport-layer-bucket.s3.<region>.amazonaws.com`	ECR image layers
`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 image repositories, allow your mirror’s hostname. Customer Distribution (088332244652) remains required for any service still using its default images. Allow public.ecr.aws and the ECR Public API only for images that actually use public ECR, such as the customer-run tunnel connector; public ECR is not the default application registry.

Catalog URL

Set mcp_catalog_api_url = "https://mcp-catalog.prod.runlayer.com" for production self-hosted, or omit it and rely on the application default (https://mcp-catalog.prod.runlayer.com). Pointing at staging with a production catalog API key typically returns 401. 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

Required from the backend / worker 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 uses Bedrock unless an admin moves it to another provider)
`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, unless an admin picks another provider’s model under Runlayer Assistant model in Settings → AI Providers. Default Assistant model: global.anthropic.claude-opus-4-8. 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 runtime subnets

For AgentCore VPC mode, allow the following from runlayer_agentcore_consumer_private_subnet_ids. Allow HTTPS / TCP 443, DNS through your configured resolver, and long-lived HTTPS WebSocket connections to Runlayer.

Destination	Purpose
Your Runlayer application hostname	Callbacks, model and MCP requests, memory, and artifact coordination; private access through PrivateLink when configured.
A separate model gateway hostname, if configured	Model requests.
`api.ecr.<region>.amazonaws.com` / `ecr.<region>.amazonaws.com`	Image authentication and metadata.
Your image registry, normally `088332244652.dkr.ecr.<region>.amazonaws.com`	Sandbox image pull.
`prod-<region>-starport-layer-bucket.s3.<region>.amazonaws.com`	ECR image layers.
`<sandbox-files-bucket>.s3.<region>.amazonaws.com`	Sandbox files, artifacts, and persistent state.
`logs.<region>.amazonaws.com`	CloudWatch Logs.
`models.dev`, `models.opencode.ai`, `registry.npmjs.org`	Catalog and dependency retrieval for images using OpenCode startup, including images that preboot OpenCode when Pi is selected.
The hostname in `runlayer_agent_sandbox_sentry_dsn`, if set	Sandbox error reporting.

Use the S3 hostname forms in your deployment’s URLs, including <bucket>.s3.amazonaws.com when used. AWS VPC endpoints can replace public AWS access, but must be reachable in the AgentCore consumer VPC, with policies allowing the buckets above. See AWS AgentCore VPC requirements. For Runlayer-routed model and MCP calls, provider and connector API access originates from the backend/gateway. Direct browsing, Git clones, package installation, or custom code require additional runtime destinations. If the sandbox egress proxy is enabled, also allow TCP 3128 to its private endpoint. Runlayer, S3, and startup traffic before proxy configuration still need the access above.

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 ECS networking

Same-VPC consumer subnets are fine when they already have NAT/HTTPS egress. Details: ECS networking 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
`generativelanguage.googleapis.com`	Google AI Studio AI provider	Gemini 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, distribution.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	Customer Distribution `088332244652.dkr.ecr…`, ECR API, and S3 image-layer access (or your configured mirror)
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
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
Runlayer Operator
Networking
OAuth Broker

Enable

Control

Self-Hosted Deployment

Operations

Cookbook

Integrations

Connectors

Resources

Network and Egress Requirements

Plan network access before deployment

Core platform (always)

Catalog URL

Binary package CDN

AuthKit domain

Agents and Runlayer Assistant

AgentCore runtime subnets

AgentCore with WAF IP allowlisting

ToolGuard (GPU) bootstrap

Feature-conditional (backend / worker)

Optional monitoring (Sentry)

AWS VPC endpoints

Symptom → missing egress

​Plan network access before deployment

​Core platform (always)

​Catalog URL

​Binary package CDN

​AuthKit domain

​Agents and Runlayer Assistant

​AgentCore runtime subnets

​AgentCore with WAF IP allowlisting

​ToolGuard (GPU) bootstrap

​Feature-conditional (backend / worker)

​Optional monitoring (Sentry)

​AWS VPC endpoints

​Symptom → missing egress

​Related pages

Plan network access before deployment

Core platform (always)

Catalog URL

Binary package CDN

AuthKit domain

Agents and Runlayer Assistant

AgentCore runtime subnets

AgentCore with WAF IP allowlisting

ToolGuard (GPU) bootstrap

Feature-conditional (backend / worker)

Optional monitoring (Sentry)

AWS VPC endpoints

Symptom → missing egress

Related pages