Apollo Router is a high-performance graph router written in Rust for running Apollo Federation 2 supergraphs. It sits in front of your subgraphs and handles query planning, execution, and response composition.
This skill generates version-correct configuration.
Router v1 and v2 have incompatible config schemas in several critical sections (CORS, JWT auth, connectors). Always determine the target version before generating any config.
Step 1: Version Selection
Ask the user
before generating any config
:
Which Apollo Router version are you targeting?
[1] Router v2.x (recommended — current LTS, required for Connectors)
open defaults (introspection on, sandbox on, errors exposed, text logging)
Load the appropriate base template from:
templates/{version}/production.yaml
templates/{version}/development.yaml
Step 3: Feature Selection
Ask which features to include:
JWT Authentication
CORS (almost always yes for browser clients)
Operation Limits
Traffic Shaping / Rate Limiting
Telemetry (Prometheus, OTLP tracing, JSON logging)
APQ (Automatic Persisted Queries)
Connectors (REST API integration — Router v2 only; GA key is
connectors
, early v2 preview key was
preview_connectors
)
Subscriptions
Header Propagation
Step 4: Gather Parameters
For each selected feature, collect required values.
Use section templates from
templates/{version}/sections/
for
auth
,
cors
,
headers
,
limits
,
telemetry
, and
traffic-shaping
.
For Connectors in v2, use
templates/v2/sections/connectors.yaml
as the source.
For APQ and subscriptions, copy the snippet from the selected base template (
templates/{version}/production.yaml
or
templates/{version}/development.yaml
) or from references.
Only offer Connectors when
ROUTER_VERSION=v2
.
CORS
List of allowed origins (never use
"*"
for production)
JWT Authentication
JWKS URL
Issuer(s) — note: v1 uses singular
issuer
, v2 uses plural
issuers
array
Connectors (v2 only)
Subgraph name and source name (used as
connectors.sources..
)
Optional
$config
values for connector runtime configuration
If migrating old v2 preview config, rename
preview_connectors
to
connectors
Operation Limits
Present the tuning guidance:
Operation depth limit controls how deeply nested a query can be.
Router default: 100 (permissive — allows very deep queries)
Recommended starting point: 50
Lower values (15–25) are more secure but will reject legitimate queries
in schemas with deep entity relationships or nested fragments.
Higher values (75–100) are safer for compatibility but offer less
protection against depth-based abuse.
Tip: Run your router in warn_only mode first to see what depths your
real traffic actually uses, then tighten:
limits:
warn_only: true
What max_depth would you like? [default: 50]
The same principle applies to
max_height
,
max_aliases
, and
max_root_fields
.
Telemetry
OTEL collector endpoint (default:
http://otel-collector:4317
)
Prometheus listen port (default:
9090
)
Trace sampling rate (default:
0.1
= 10%)
Traffic Shaping
Client-facing rate limit capacity (default: 1000 req/s)
Router timeout (default: 60s)
Subgraph timeout (default: 30s)
Step 5: Generate Config
Load the correct version template from
templates/{version}/
Assemble section templates for supported sectioned features, then merge base-template snippets for APQ/subscriptions as needed
Inject user-provided parameters
Add a comment block at the top stating the target version
Step 6: Validate
Run the
post-generation checklist
:
All env vars referenced in config are documented
CORS origins don't include wildcards (production)
Rate limiting is on
router:
(client-facing), not only
all:
(subgraph)
JWT uses
issuers
(v2) not
issuer
(v1), or vice versa
If production: introspection=false, sandbox=false, subgraph_errors=false
Health check is enabled
Homepage is disabled (production)
Run:
router config validate
if Router binary is available
Required Validation Gate (always run)
After generating or editing any
router.yaml
, you MUST:
Run
validation/checklist.md
and report pass/fail for each checklist item.
Run
router config validate
if Router CLI is available.
If Router CLI is unavailable, state that explicitly and still complete the checklist.
Do not present the configuration as final until validation is completed.
Step 7: Conditional Next Steps Handoff
After answering any Apollo Router request (config generation, edits, validation, or general Router guidance), decide whether the user already has runnable prerequisites:
GraphOS-managed path:
APOLLO_KEY
+
APOLLO_GRAPH_REF
, or
Local path: a composed
supergraph.graphql
plus reachable subgraphs
If prerequisites are already present, do not add extra handoff text.
If prerequisites are missing or unknown, end with a concise
Next steps
handoff (1-3 lines max) that is skill-first and command-free:
Suggest the
rover
skill to compose or fetch the supergraph schema.
Suggest continuing with
apollo-router
once the supergraph is ready to validate and run with the generated config.
If subgraphs are missing, suggest
apollo-server
,
graphql-schema
, and
graphql-operations
skills to scaffold and test.
Do not include raw shell commands in this handoff unless the user explicitly asks for commands.
Quick Start (skill-first)
Use this
apollo-router
skill to generate or refine
router.yaml
for your environment.
Choose a runtime path:
GraphOS-managed path: provide
APOLLO_KEY
and
APOLLO_GRAPH_REF
(no local supergraph composition required).
Local supergraph path: use
graphql-schema
+
apollo-server
to define/run subgraphs, then use
graphql-operations
for smoke tests, then use the
rover
skill to compose or fetch
supergraph.graphql
.
Use this
apollo-router
skill to validate readiness (
validation/checklist.md
) and walk through runtime startup inputs.
Default endpoint remains
http://localhost:4000
when using standard Router listen defaults.
If the user asks for executable shell commands, provide them on request. Otherwise keep Quick Start guidance skill-oriented.
Running Modes
Mode
Command
Use Case
Local schema
router --supergraph ./schema.graphql
Development, CI/CD
GraphOS managed
APOLLO_KEY=... APOLLO_GRAPH_REF=my-graph@prod router
Production with auto-updates
Development
router --dev --supergraph ./schema.graphql
Local development
Hot reload
router --hot-reload --supergraph ./schema.graphql
Schema changes without restart
Environment Variables
Variable
Description
APOLLO_KEY
API key for GraphOS
APOLLO_GRAPH_REF
Graph reference (
graph-id@variant
)
APOLLO_ROUTER_CONFIG_PATH
Path to
router.yaml
APOLLO_ROUTER_SUPERGRAPH_PATH
Path to supergraph schema
APOLLO_ROUTER_LOG
Log level (off, error, warn, info, debug, trace)
APOLLO_ROUTER_LISTEN_ADDRESS
Override listen address
Reference Files
Configuration
— YAML configuration reference
Headers
— Header propagation and manipulation
Plugins
— Rhai scripts and coprocessors
Telemetry
— Tracing, metrics, and logging
Connectors
— Router v2 connectors configuration
Troubleshooting
— Common issues and solutions
Divergence Map
— v1 ↔ v2 config differences
Validation Checklist
— Post-generation checks
CLI Reference
router [OPTIONS]
Options:
-s, --supergraph Path to supergraph schema file
-c, --config Path to router.yaml configuration
--dev Enable development mode
--hot-reload Watch for schema changes
--log Log level (default: info)
--listen Override listen address
-V, --version Print version
-h, --help Print help
Ground Rules
ALWAYS determine the target Router version (v1 or v2) before generating config
DEFAULT to v2 for new projects
ALWAYS include a comment block at top of generated config stating the target version
ALWAYS use
--dev
mode for local development (enables introspection and sandbox)
ALWAYS disable introspection, sandbox, and homepage in production
PREFER GraphOS managed mode for production (automatic updates, metrics)
USE
--hot-reload
for local development with file-based schemas
NEVER expose
APOLLO_KEY
in logs or version control
USE environment variables (
${env.VAR}
) for all secrets and sensitive config
PREFER YAML configuration over command-line arguments for complex setups
TEST configuration changes locally before deploying to production
WARN if user enables
allow_any_origin
or wildcard CORS in production
RECOMMEND
router config upgrade router.yaml
for v1 → v2 migration instead of regenerating from scratch
MUST run
validation/checklist.md
after every router config generation or edit
MUST run
router config validate
when Router CLI is available
MUST report when CLI validation could not run (for example, Router binary missing)
MUST append a brief conditional handoff when runtime prerequisites are missing or unknown
MUST make this handoff skill-first and avoid raw shell commands unless the user explicitly requests commands
MUST keep Quick Start guidance skill-first and command-free unless the user explicitly requests commands
MUST state that Rover is required only for the local supergraph path; GraphOS-managed runtime does not require local Rover composition
USE
max_depth: 50
as the default starting point, not 15 (too aggressive) or 100 (too permissive)
RECOMMEND
warn_only: true
for initial limits rollout to observe real traffic before enforcing