Will my clients notice the switch?

Clients keep the same endpoint, request format, and response shape. Error messages and some status codes differ from Apollo by default. If clients parse them, turn on apollo_compatibility_flags, plus apollo_router_compatibility_flags for Apollo Router variable errors. Every flag is off by default.

What replaces Rhai scripts and coprocessors?

Custom modules. You write the same logic in Go, with hooks on the client request, before and after each subgraph request, and on startup and shutdown, and compile it into the router binary. There is no extra network hop.

Can I keep my persisted query IDs?

Yes. Push your Apollo persisted query manifest with wgc operations push. Cosmo keeps the id of each operation in an Apollo manifest, so clients keep sending the IDs they send today. Custom IDs require APQ to be disabled.

Can I migrate gradually?

Yes, in two ways. Move the schema registry to Cosmo first and keep Apollo Router serving traffic from a supergraph that Cosmo builds. Or run Cosmo Router next to Apollo Router against the same subgraphs and shift traffic at your load balancer, raising the share as error rates and latency hold.

Do I need to complete the GraphOS migration first?

No, but it is the shortest path. The one-click GraphOS migration moves your graphs into Cosmo, and npx wgc federated-graph fetch then downloads the router config. You can also create the graphs manually with wgc.

Is Cosmo Router open source?

Yes. Cosmo Router is licensed under Apache 2.0. You can read the code, run it yourself, and keep running it if you stop using Cosmo Cloud.

Migrate from Apollo Router to Cosmo Router | WunderGraph Cosmo

Q: Do I need to change my subgraphs?

Not if their directives are listed in the Federation compatibility matrix, which covers v1 and v2 up to v2.5. Cosmo Router talks to subgraphs over the same HTTP and GraphQL protocols as Apollo Router, so subgraph code, resolvers, and schemas stay as they are. Test any directive the matrix does not list before you cut over.

The problem

Router migration feels too risky to attempt

Compatibility unknowns, potential subgraph changes, and client coordination all add up to a project that seems harder than it is.

Directive compatibility is unknown before you commit

Teams cannot risk a router swap if they are unsure whether Federation v1 and v2 directives behave the same way. Uncertainty about compatibility blocks migration planning entirely.

Subgraph modification risk is too high

If the new router requires changes to subgraph schemas or resolvers, the migration scope expands from a router deployment into a multi-team schema rewrite.

Client-side changes cannot be coordinated across consumers

Changing how GraphQL clients connect to the router requires coordinating updates across every consumer of the API. Teams need the router swap to be transparent to clients.

Our solution

Swap the router, keep your subgraphs

Cosmo Router implements the Federation v1 and v2 directives in its compatibility matrix (up to v2.5). After migrating your graph configuration, fetch the router config from Cosmo and deploy. Subgraph code stays as it is. Router-side customizations need porting, and the next section lists them.

From Apollo Router to Cosmo Router

Complete the Apollo GraphOS graph migration (or set up Cosmo manually).
Deploy Cosmo Router using the router config available in Cosmo after migration. Fetch it with: npx wgc federated-graph fetch <graph-name>.
Update your load balancer or API gateway to route traffic to Cosmo Router.
Cosmo Router handles query planning, subgraph orchestration, and response aggregation.
Subgraphs whose directives are in the compatibility matrix (up to v2.5) need no changes. If clients parse Apollo error codes or status codes, turn on the Apollo compatibility flags, which are off by default. For a detailed breakdown of how Cosmo handles Apollo Router compatibility, see the compatibility post.
Access Cosmo Studio immediately for observability, analytics, and schema management.

Deploy once. Existing subgraphs keep working.

Apollo Router Migration

Before & After

Before Cosmo	With Cosmo
Concerns about Federation directive compatibility	Federation v1 and v2 directives up to v2.5, listed in a public compatibility matrix
Manual router configuration required	Router config available in Cosmo after migration: fetch it with npx wgc federated-graph fetch <graph-name>
Subgraph modification risk	No subgraph changes for standard Federation directives
Client updates needed after router swap	Same endpoint and request format; Apollo error formats available through opt-in compatibility flags
Rhai scripts and coprocessors on the request path	Go custom modules compiled into the router binary

Immediate gains

Cosmo Studio from day one

Advanced observability: Real-time metrics, request tracing, and schema analytics are available in Cosmo Studio the moment the router is live.
Schema management: Manage subgraphs, view composition results, and track schema changes across all environments from a single interface.

How Apollo Router migration works

01

Router config available immediately.

Migrate

Use the Apollo GraphOS migration tool to bring your graph configuration into Cosmo. After migration, fetch the router config with npx wgc federated-graph fetch <graph-name>. Manual Cosmo setup is also supported.

02

Any container platform.

Deploy

Deploy Cosmo Router to your infrastructure using the router config fetched with npx wgc federated-graph fetch <graph-name>. The router runs as a binary, in Docker, or on Kubernetes. Subgraph endpoints do not change.

03

Gradual cutover.

Route

Point your load balancer or API gateway at Cosmo Router. Shift traffic in steps and keep Apollo Router running until error rates and latency match, so rollback is a weight change.

04

Observability from day one.

Monitor

Access Cosmo Studio for real-time observability, schema analytics, and federated graph management. These capabilities are available from the moment the router is live.

Before you switch

What to inventory in your Apollo Router setup

Subgraphs rarely change. These six parts of the router do, and each has a Cosmo equivalent.

01Federation version and directives
Check your subgraphs against the Federation compatibility matrix. It lists Federation v1 and v2 directives up to v2.5, including @authenticated and @requiresScopes. Test any subgraph that uses a directive the matrix does not list before you switch.
02Rhai scripts and coprocessors
Port Rhai scripts and coprocessor logic to Go custom modules, which compile into the router binary. One catch: a module that hooks in before each subgraph request turns off request deduplication, so put header and auth logic in the client-request hooks where you can.
03Error formats and status codes
By default Cosmo returns its own error messages. The Apollo compatibility flags switch on Apollo-style variable errors, a 400 status on validation failures, value completion, and suppressed fetch errors. They are all off by default. List the error codes your clients branch on, then turn on only the flags that cover them.
04Persisted queries
Export your Apollo persisted query manifest and push it with wgc operations push. Cosmo keeps each operation id from Apollo-format manifests, so mobile apps already in the store keep working. Custom IDs require APQ to be disabled.
05Router YAML
Cosmo Router has its own config.yaml. Set up header rules, CORS, JWT authentication, traffic shaping, and telemetry exporters there. Header propagation is off by default in both directions, so add an explicit rule for every header a subgraph needs.
06Client identification
Cosmo reads the ApolloGraphQL-Client-Name and ApolloGraphQL-Client-Version headers as well as its own GraphQL-Client-Name headers, so per-client analytics in Cosmo Studio work without client changes.

Cutover

Cut over in steps, not all at once

Move the registry first. Migrate your graphs to Cosmo and keep Apollo Router serving traffic. A webhook you set up runs wgc federated-graph fetch on every schema change and hands Apollo Router a supergraph that Cosmo composed. You get Cosmo schema checks and the registry before you touch the router. The step-by-step tutorial includes a demo project.

Then run both routers. Deploy Cosmo Router next to Apollo Router against the same subgraphs and send it a small share of traffic from your load balancer. Compare error rates and latency against your existing Apollo metrics, raise the share as they hold, and roll back by changing the weight.

Cosmo's documented shadow mode works on subgraphs through feature flags, not between two routers. To compare router responses without returning them to clients, mirror requests at your load balancer or proxy.

What teams saw after the swap

monday.com's API edge ran on Apollo Router with a Node.js coprocessor. They moved it to Cosmo Router and built a Go gateway in front of the router that runs authentication, authorization, rate limits, and other checks.

“At cutover, the router stopped waiting on coprocessor round trips, and the edge’s p99 fell from about 490 ms to about 200 ms.”

monday.com engineering, One prompt, dozens of API calls: rebuilding the monday.com API edge for AI Agents. Speed wasn't the main reason they chose Cosmo; they picked it because it is easy to modify, profile, and adapt.

TravelPass Group handles PCI data and was an early GraphQL adopter that ran Apollo. They run the Cosmo Router self-hosted.

“It only took us about a day to reconfigure everything and get started with Cosmo.”

Tyler Hawkins, Backend Tech Lead, TravelPass Group. Read the case study.

What's included

Everything you need for the router swap

Available on Free, Pro, and Enterprise.

Federation v1 and v2 support

The Federation v1 and v2 directives in the compatibility matrix (up to v2.5) are supported. Existing subgraph schemas work without modification.

Router config ready after migration

After migration, fetch the router config with npx wgc federated-graph fetch <graph-name>. You still write the router's own config.yaml for headers, auth, and telemetry.

No subgraph rewrites

Cosmo Router talks to subgraphs over the same HTTP and GraphQL protocols as Apollo Router. Subgraph code, resolvers, and schemas that use directives in the compatibility matrix stay as they are.

Client compatibility

Clients keep the same endpoint and request format. Error messages and status codes differ from Apollo by default; turn on the Apollo compatibility flags if clients depend on them.

Switch to Cosmo Router today

Migrate your graph from Apollo GraphOS, fetch the router config, and deploy Cosmo Router.

Start Free Read the Docs

Replace Apollo Router with Cosmo Router without rewriting your subgraphs