## What registration records

An enclave runs in the customer's Kubernetes. The controlplane keeps a registry
of enclaves so it can fan a correctly-scoped policy snapshot out to each one. To
enter the registry an enclave needs a broker identity — the credential its broker
uses to authenticate to the controlplane's operator API and pull desired state.

`dvx enclaves register-broker` mints that identity through the authenticated
operator API. The controlplane creates the enclave's Zitadel service identity,
grants it `enclaves:read`, binds its `enclave.subject`, and returns the key
**once**. Registration is metadata only: a name, a canonical enclave id, and the
owning org. No sovereign data crosses this path.

Each enclave serves exactly one org, fixed at registration. There is no post-hoc
org assignment, so `--owning-org` is required.

{{< planenote plane="controlplane" >}}
Authoring goes through the controlplane operator API. Set `--controlplane` (or
`DVX_CONTROLPLANE_URL`) and authenticate with a service-account key
(`--zitadel-key` / `DVX_ZITADEL_KEY`) or a token file. The controlplane never
receives sovereign data; it only mints identity and holds registry metadata.
{{< /planenote >}}

## Mint the broker identity

The minted key is the enclave's sole controlplane credential. It is written once,
with `0600` perms, to `--out`; deliver it out of band into the enclave cluster
(for example as a Kubernetes Secret). Use `--out -` to stream the raw key JSON to
stdout and pipe it straight into a Secret without touching disk.

{{< terminal title="dvx" prompt="$" >}}
$ dvx enclaves register-broker \
    --controlplane https://cp.example.com \
    --name daevix-dev \
    --owning-org org_acme \
    --out broker-key.json
enclave-id=enc_7f3a...
registered broker for enclave "enc_7f3a..." (subject "..."); key written to broker-key.json
{{< /terminal >}}

Pass `--enclave-id` to supply an explicit canonical id; omit it to have the
controlplane mint a random one. The minted id is echoed on stderr as
`enclave-id=<id>` so a provisioning script can capture it — the enclave is
deployed carrying its own `DVX_ENCLAVE_ID`.

## Let it converge

Nothing is pushed into the cluster from outside. The enclave's broker authenticates
with its minted key and **pulls** signed desired-state snapshots from the
controlplane, then reconciles the cluster toward them on its next pull. Author
policy on the controlplane; the enclave converges on its own schedule.

## Discover and manage enclaves

`dvx enclaves list` returns the enclaves your org can reach and their
client-reachable addresses (relay and broker URLs), so the CLI and console can
target them without hand-configured URLs.

`dvx enclaves refresh` caches that same discovery into the local profile
(`~/.config/dvx/profile.json`) so commands like `dvx audit` and `dvx secret` can
target an enclave by `--enclave-id` without a URL. Those commands also
auto-refresh the cache when it goes stale.

{{< terminal title="dvx" prompt="$" >}}
$ dvx enclaves list --controlplane https://cp.example.com
[
  {
    "enclave_id": "enc_7f3a...",
    "name": "daevix-dev",
    "status": "active",
    "owning_org_id": "org_acme",
    "relay_url": "https://...",
    "broker_url": "https://..."
  }
]
$ dvx enclaves refresh --controlplane https://cp.example.com
cached 1 enclave(s) to /home/you/.config/dvx/profile.json
{{< /terminal >}}

Remove an enclave from the registry with `dvx enclaves delete`, addressing it by
`--name` or `--enclave-id`.

{{< terminal title="dvx" prompt="$" >}}
$ dvx enclaves delete --controlplane https://cp.example.com --name daevix-dev
deleted enclave "daevix-dev"
{{< /terminal >}}