> Section: [7. Running it](https://jaque.sh/docs/deployment/overview.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; that is the boundary working, not a limitation.

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

Acknowledgements and downtimes issued at the aggregator are forwarded
to the realm that owns the object, and that realm records the
aggregator's service identity as the author -- not the person who
clicked. 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.

See [Topologies](https://jaque.sh/docs/deployment/topologies.md) for the six `-target` roles of a single
deployment; the aggregator sits above deployments, not among their
roles.