TL;DR
Cosmo Studio is the operator console for a federated GraphQL graph: schema registry, schema checks, analytics and distributed tracing, playground, and organization management. Use it to see, validate, and observe the live graph. The router executes every request; WunderGraph Hub is the main place a schema change is designed and agreed on before it ships.
Glossary
Schema registry
The system of record inside Cosmo Studio for the composed schema and every subgraph schema that feeds it.
A schema that fails to compose never reaches the router; routers keep serving the last valid composition.
Schema check
A validation Cosmo Studio runs against a proposed schema change before it ships: composition, breaking-change detection, an operation check against real traffic, and lint.
Teams see exactly which clients and operations a change would break, before merge.
Operation check
The part of a schema check that compares a breaking change against the schema usage data your routers report. If no active client uses the affected field, the check passes.
Teams stop treating every breaking change as automatically unsafe; usage data decides.
Schema explorer
The interactive view of the composed schema inside Studio, with search, field-level usage data, and deprecated-field tracking built in.
Teams can tell whether a field is safe to remove before they try to remove it.
Distributed tracing
The trace view inside Studio Analytics that shows the path a request took across the router and every subgraph it touched, span by span.
Debugging a slow or failed federated request stops being guesswork.
Schema contract
A filtered view of a source graph, generated from @tag annotations, that exposes a subset of the schema to a specific audience.
One source schema can serve internal teams on the full graph, and partners or the public through their own contract graphs and routers.
What Is Cosmo Studio?
WunderGraph Cosmo Studio is the web console for WunderGraph Cosmo, the open-source GraphQL federation platform. The CLI and the router build and run the graph; Studio is where a team sees it, understands it, and decides whether a change is safe to ship.
Every federated graph and subgraph created through the Cosmo CLI (wgc) shows up in Studio: connected subgraphs, label matchers, composition status, the schema registry, and the schema checks run against it. Studio also holds the changelog for every schema change, a bundled GraphiQL playground for running queries against the graph, and the analytics dashboard: request volume over time and distributed tracing across the router and its subgraphs.
Each federated graph opens on an overview page that shows its composition status and router URL, a map of its subgraphs with P95 latency and requests per minute for each service, requests and errors over time, and the ten most requested operations of the past week.
Put simply, Studio is the operating surface for a federated graph once composition and routing are working. It is part of Cosmo, not a separate product bolted on, and it is where a platform team works with the graph day to day.
Studio vs Router vs Hub
Studio, Router, and Hub are three different WunderGraph surfaces. Here is how they split:
| Router | Studio | Hub | |
|---|---|---|---|
| Layer | Runtime | Operate and observe | Design and govern |
| Job | Plans and executes every query against the composed supergraph | Schema registry, schema checks, analytics, tracing, playground, org management | Where teams design schema changes and agree on them before anything ships |
| Who touches it | Platform teams deploy and configure it; clients send it requests | Platform and backend teams operating the live graph | Frontend and backend teams designing the next change |
| Where it sits in the lifecycle | After a change ships | Registry-side, around publish and check time | Before a change ships |
Router is the hot path for every request; it can serve a built-in GraphQL playground, but it has no management console. Studio is the console for what is already live: the registry, the checks that gate a publish, and the analytics that show how the live graph behaves. Hub is upstream of all of it, the place where a "dream query" becomes an agreed-on schema change before it ever reaches the registry.
Schema registry and explorer
The schema registry is the system of record for a federated graph’s schema. It shows the current composed schema, the individual schema of every subgraph that feeds it, and when the schema was last updated. The compositions page sits alongside it: the inputs and errors of every composition, every composed version, and which version the router is currently serving.
The changelog is the history behind that current state: every addition and deletion to the schema, in order, so a team can see exactly what changed and when without reconstructing it from CI logs.
Studio also shows which types and fields carry @authenticated or @requiresScopes, so access requirements are visible in the same place as the schema itself. For now, these appear only in the Router Schema view.
Schema explorer
The schema explorer is where a team actually reads the composed schema: press Cmd/Ctrl+K to search it and jump to any type.
This is more than a static schema browser. Every field carries live usage data pulled from the field-usage analytics below, so a team can see who calls a field before deciding whether it is safe to change or remove. And every deprecated field is surfaced in one place, next to its usage.
Schema checks: validate changes before production
A schema check validates a proposed change before it ships. Cosmo Studio looks for four kinds of errors, not one:
Composition errors
Whether the proposed subgraph schema composes with every other subgraph in the federated graph. A schema with composition errors never reaches the router: routers keep serving the last valid composition until composition succeeds.
Breaking change detection
Whether the proposed schema removes or changes anything an existing client operation depends on.
Operation checks
Whether a detected breaking change actually affects real traffic. Cosmo Studio compares the change against the schema usage data your routers send to Cosmo Cloud, and fails the check only if an active client uses what changed.
Lint checks
Whether the proposed schema violates the namespace’s configured lint rules.
The same check runs any graph pruning rules the namespace has configured, and it also composes every contract built on the graph and every enabled feature flag the subgraph belongs to, so a change that breaks one of those gets caught at the same time.
What operation checks change about "breaking"
Most schema-check tooling treats every breaking change the same way: it fails, full stop. Cosmo Studio’s operation checks ask a more useful question. If you propose a breaking change and no active client uses the affected field, the check passes, because nothing in production actually breaks. One limit: Cosmo does not track directive usage yet, so changing or deleting a directive always counts as non-breaking.
By default, an operation check compares the proposed change against the last 7 days of client traffic; that lookback window is configurable per namespace from Policies, up to your plan’s limit. That is a separate setting from how long Cosmo Cloud keeps data overall, which depends on your plan.
Run checks from CI with wgc subgraph check, or wire them into a PR-based workflow with the GitHub integration. When a breaking change is genuinely safe to ship anyway, teams with GitHub integration can override it manually rather than block the release.
Operations and overrides
The operations page is the two-panel view behind the check: a searchable, filterable list of every operation executed against the graph, sorted by request count, latency, or error rate, with a details panel showing which clients call it and which deprecated fields it touches. The check page answers "what breaks after a schema change" just as concretely: open an affected operation to see every change that hits it, with each change linked to the schema explorer and to field usage for the check’s time window.
When a check flags a breaking change you have already decided is safe, overrides let you ignore that specific change for that operation, or ignore the operation entirely, in future checks. Overrides only affect operation checks; they never suppress composition errors, breaking-change detection, or lint.
Subgraph check extensions
For teams that need checks Cosmo does not run out of the box, subgraph check extensions (Enterprise plan) send a request to your own endpoint every time a check runs (signed with HMAC if you set a secret), and let that endpoint return additional lint issues or fail the check outright. The endpoint must be reachable from Cosmo, and any response other than a 200 or 204 fails the check. It is a way to enforce internal naming standards, notify another team of an upcoming breaking change, or hook schema checks into an existing internal pipeline, without waiting on WunderGraph to build the specific rule.
Analytics, tracing, and field usage
Studio’s analytics answer "how is this graph actually being used," at three levels of resolution: aggregate metrics, individual traces, and per-field usage.
Metrics and traces
Metrics gives the overview: request rate, P95 latency, and error rate over a selected time range, filterable by operation, client name, and client version. Traces lists individual requests (how many depends on the router’s OpenTelemetry sampling rate), groupable by operation, client, or error message, with auto-refresh down to 10-second intervals for live debugging.
Clicking into a trace opens distributed tracing: the path a request took through the router and every subgraph it touched, with per-span attributes, service boundaries, and errors. This is where a slow federated request stops being a mystery and becomes a specific span you can point at.
Field usage and client identification
Schema field usage tracks every GraphQL type down to which clients call it, which operations use it, and how many requests it has served, first and last seen. It is the data layer behind the schema explorer’s usage indicators and the operation checks above.
None of that per-client breakdown works without client identification. Sending GraphQL-Client-Name and GraphQL-Client-Version headers (or the Apollo-compatible variants, for migration) with every request is what lets Studio attribute usage to a specific client instead of an anonymous blob of traffic.
Playground++
Studio bundles an enhanced GraphiQL, not a link out to a separate tool. With the X-WG-TRACE header on a request, which new tabs send unless you change the default headers, the playground shows the query execution plan with timings, inputs, and outputs for each subgraph, in a tree view or a waterfall view. The data comes from the router’s Advanced Request Tracing, which is on by default (it needs router 0.42.3 or later and a connection to the control plane) and, in production, answers only requests that carry a signed token from Studio. It is the fastest way to see why a specific query is slow, without leaving the query editor.
Custom scripts extend the playground with pre-flight, pre-operation, and post-operation hooks, so teams can inject auth tokens, validate responses, or transform output for a given request lifecycle, with sensitive values kept in browser-scoped environment variables rather than in the script itself.
A shareable-link feature lets a team send a playground session (the operation, plus variables and headers if you choose) as a single URL, which turns "can you try this query" into a link instead of a screen-share. Scripts never go into the link, and anyone with the link can read shared headers, so leave tokens out.
Governance and schema hygiene
Design-time governance, agreeing on a change before it exists, is mainly Hub’s job. Studio’s slice of governance is registry-side enforcement: the rules that run every time a schema is checked. A namespace can also turn on proposals, which the team reviews in Studio; checks and publishes can then be required to match a proposal before a change goes through.
Lint policy
Once a namespace turns on the linter, the rules you configure run on every check. The available rules cover naming and structure conventions: camelCase fields, PascalCase types, no Type prefix or suffix on type names, an Input suffix (and no Input prefix) on input types, alphabetically sorted fields and enum values, required descriptions on every type, and a required reason on every @deprecated directive. Violations configured as errors fail the check; violations configured as warnings do not.
Graph pruning
The graph pruning linter flags schema hygiene issues that lint rules do not catch: fields nobody uses, fields deprecated but never removed, and fields deleted without a deprecation period first. A configurable grace period gives a newly modified field time before pruning rules start enforcing against it, and enterprise plans can set a custom usage-check window for the underlying traffic analysis.
Schema contracts
Schema contracts filter a source graph into a smaller, audience-specific graph using the @tag directive: tag a field internal, exclude internal from a contract, and that contract’s clients never see the field, while the full graph still resolves it correctly internally. It is the mechanism behind serving one API to internal teams and a stripped-down version to partners or the public, from one underlying schema. Each contract is a graph of its own, served by its own router. Filtering also works the other way: --include keeps only the types that carry the tag, along with their fields.
Contracts recompose automatically whenever the source graph changes, and schema checks run against every contract the same way they run against the source, so a change that breaks a contract’s clients gets caught at the same time as one that breaks the main graph.
Graph documentation
A federated or subgraph can carry its own markdown documentation, published with the --readme flag in wgc, so ownership and context live next to the schema instead of in a wiki page nobody finds.
Access control and enterprise readiness
Role-based access control (RBAC) assigns permissions to groups rather than individuals, and groups can be linked to both organization members and API keys, so a CI system and a human can share the same access policy. Groups require RBAC to be enabled at the organization level, available starting on the Scale plan.
Single sign-on, available starting on the Scale plan, connects Cosmo to any OpenID Connect provider (Okta, Auth0, Keycloak, Microsoft Entra, or others), auto-enrolling users with roles based on your configured mappings. An organization can connect more than one OIDC provider at once, and on the Enterprise plan can restrict specific namespaces to specific login methods, which matters for orgs that need to keep one namespace behind a stricter identity provider than the rest. API keys are not bound by these login-method restrictions, so CI can still reach a restricted namespace. On the Enterprise plan, SCIM layers on top for automated user provisioning and deprovisioning from the identity provider directly.
API keys authorize wgc for CI and local CLI use, scoped to a group and an expiry. The audit log records who did what and when, and whether a user acted directly or through an API key, so security and compliance reviews do not depend on institutional memory. Sessions renew every 8 hours while a user is active, expire after 72 hours idle, and hit a hard 14-day maximum lifetime regardless of activity; disconnecting SSO logs out every SSO user and downgrades them to the viewer role.
Alerts, webhooks, and fleet operations
Studio notifies a team when a federated graph’s schema changes, through Slack integration or HMAC-signed webhooks, so schema changes surface where a team already works instead of requiring someone to check Studio directly.
Cluster management gives a live view of every running router instance (router 0.66.1 or later): version, cluster, uptime, and CPU and memory trends, reported through the router’s OpenTelemetry instrumentation. It answers "which composition is actually live, on which instances" without SSHing anywhere.
Open source and deployment
WunderGraph Cosmo is open source under Apache 2.0, and that includes Studio itself, along with the router, control plane, and CLI. Use Studio in the managed Cosmo Cloud, or run it yourself as part of a self-hosted Cosmo stack (the Cosmo Helm chart ships Studio as one of its sub-charts) when data residency or compliance requirements mean the graph cannot leave your own infrastructure.
Teams running Cosmo in production
A few teams running federated GraphQL on WunderGraph Cosmo in production:
Tens of ms faster at peak
"Now, Cosmo presents all the relevant stats—how many queries run, their response times, and key performance metrics—making it much easier to communicate what's happening under the hood." Advanced Request Tracing, shown in Studio, helped the team find slow queries and debug production issues faster after moving off a home-built federation layer.
Read case study
Schema checks catch breaks in CI
"The checks that Cosmo does is a super great thing to have. I’m referring to actual checks on the real traffic." K Health self-hosts the router for HIPAA compliance, and Cosmo’s schema checks catch breaking changes early.
Read case study
86% less provisioned CPU
Cut provisioned CPU from 600 to 80 vCPUs across the architecture, and monthly gateway spend from about $14,000 to $9,750 (about 30% less), after moving to Cosmo.
Read case study
Migration in about one day
Migrated from Apollo to Cosmo in roughly a day. While debugging complex queries during the move, the team found errors in their schema that their previous provider never caught or reported.
Read case studyFrequently asked questions
Learn more about Cosmo Studio
Getting started
Schema registry and checks
Analytics and tracing
Access control and security
Start using Cosmo Studio
If your team is running a federated graph on Cosmo, Studio is the console you already need: a schema registry, checks that catch breaking changes before production, and analytics that show how the graph actually behaves. It is open-source, free to start, and available self-hosted or managed.
Published August 11, 2026 · WunderGraph
