> Section: [7. Running it](https://jaque.sh/docs/deployment/choose.md)
> Next: deployment/cluster-and-coordination
> Index: https://jaque.sh/llms.txt


An organization can run several jaque deployments: one per network zone
that must not share a control plane, one per team, one per acquisition.
Each is complete on its own: engines, checks, dashboard. The
aggregator is the pane of glass above them: one place to see every
problem, filter across deployments, and acknowledge from, without
opening N browser tabs.

It is the same binary. Starting `jaque` with `-realms-config` selects
the aggregator flavour: the process serves the dashboard and the query
API over the deployments the realms document declares, and runs no
checks of its own. `-realms-config` and `-config` are mutually
exclusive: an aggregator has no monitoring document.

## 1. The realms document

A *realm* is one deployment, standalone or a cluster; the aggregator
cannot tell and does not care. The realms document is its own CUE file,
read once at boot (restart to change it, same rule as `-auth-config`):

```cue
realms: {
	madrid: {
		url:   "https://jaque.mad.example.com"
		token: "the-service-identity's-plaintext-token"
	}
	lisbon: {
		url:   "https://jaque.lis.example.com"
		token: "another-token"
		proxy: "http://egress-proxy.example.com:3128"
	}
}
```

`url` is the realm's API address, `token` authenticates the aggregator
to it, and the optional `proxy` routes that realm's traffic through an
HTTP proxy. URLs must be http or https with a host; tokens must be
non-empty; an empty realms block is refused at startup.

## 2. What a realm needs

A realm needs nothing new to be aggregated: a
[service identity](https://jaque.sh/docs/deployment/security.md) in its auth document whose token the
aggregator holds, and network reachability from the aggregator. The
aggregator speaks the realm's own
[query and command API](https://jaque.sh/docs/api/command-and-query-service.md): it
never joins a realm's cluster and never reads a realm's storage, so the
API is the entire boundary. A realm without `-auth-config` cannot be
aggregated: the API boundary is what requires it.

Every realm stays fully usable with the aggregator down, and the
aggregator stays up when realms are down.

## 3. Degraded realms

With N realms, some are occasionally unreachable, and the pane of glass
is most needed exactly then. An unreachable realm keeps its last
successfully fetched rows on screen and the dashboard shows a banner
naming each unreachable realm and when it was last seen. Status rows
carry the realm they came from, the problems and hosts views grow a
realm column and filter, and the object detail shows a realm badge:
two realms may legitimately declare the same host name and the
dashboard keeps them apart.

`/realms.json` on the aggregator answers the per-realm health directly:
name, url, reachable, version, auth_enabled, and the error when a realm
does not answer.

## 4. Commands

Commands issued at the aggregator go through the aggregator's own
command service: each request wraps the realm API's request together
with the realm that owns the target, and the aggregator forwards the
inner request to that realm, which records the aggregator's service
identity as the author; the person who clicked does not appear in that
field. Passive check
results, single and batch, are forwarded the same way. Bulk actions
over a label selector are not routed through the aggregator: a
selector spans realms, and forwarding it would need a fan-out with
partial-failure semantics the command API deliberately does not
promise. Use the owning realm's own dashboard for bulk actions. A batch
of passive results targets one realm by construction, so a
mixed-realm burst is split by the sender before it reaches the
aggregator, the same doctrine as bulk actions.

See [Topologies](https://jaque.sh/docs/deployment/topologies.md) for the six `-target` roles of a single
deployment; the aggregator sits above deployments rather than being one
of those roles.