The core of the CLI
The CLI's own commands: prepare a cluster, see how it is doing, and apply reefs, Nereids, Mandates and profiles
O core do CLI
Os comandos do próprio CLI: preparar um cluster, ver como ele está, e aplicar reefs, Nereids, Mandates e profiles
The source of truth for the CLI's own commands (#477, #482 (port core into the CLI reference)): the commands of cli/src/nereus/commands/ that are not a reef's. Every command here is built, and the outputs are what it prints, taken from the walkthrough pages, which record make scene's output; a slide whose output comes from the code or from an offline run says so in its notes.
nereus system, the deprecated aliases of the first proof of concept (#409), stays out (owner's decision): its commands are the ones of this deck under their old names.
A fonte da verdade dos comandos do próprio CLI (#477, #482 (migrar o core para a referência do CLI)): os comandos de cli/src/nereus/commands/ que não são de um reef. Todo comando aqui está pronto, e as saídas são o que ele imprime, tiradas das páginas do walkthrough, que gravam a saída do make scene; um slide cuja saída vem do código ou de uma execução offline diz isso nas suas notas.
O nereus system, os aliases obsoletos da primeira prova de conceito (#409), fica de fora (decisão do dono): os seus comandos são os deste deck com os nomes antigos.
Eight groups, before any reef
- init: prepares the cluster, core and a profile
- status: one row per reef and its Nereid
- doctor: one pass or fail per check
- reef: a capability, its kinds and its command group
- nereid: the controller that looks after a reef
- mandate: binds a reef to a Nereid, with its params
Oito grupos, antes de qualquer reef
- init: prepara o cluster, o core e um profile
- status: uma linha por reef e a sua Nereid
- doctor: um pass ou fail por verificação
- reef: uma capacidade, os seus kinds e o seu grupo de comandos
- nereid: o controller que cuida de um reef
- mandate: liga um reef a uma Nereid, com os seus params
The verbs are kubectl's (ADR 0013, command conventions): create, apply, list, get and delete, and every change takes --dry-run. A reef's own commands live in its deck ([The CLI](index.html)).
Os verbos são os do kubectl (ADR 0013, convenções de comando): create, apply, list, get e delete, e toda mudança aceita --dry-run. Os comandos de um reef vivem no seu deck ([O CLI](index.html)).
Eight groups, before any reef
- profile: the reefs, Nereids and Mandates that come together
- config: the SLO, the installation and your current owner
Oito grupos, antes de qualquer reef
- profile: os reefs, Nereids e Mandates que vêm juntos
- config: o SLO, a instalação e o seu owner atual
The verbs are kubectl's (ADR 0013, command conventions): create, apply, list, get and delete, and every change takes --dry-run. A reef's own commands live in its deck ([The CLI](index.html)).
Os verbos são os do kubectl (ADR 0013, convenções de comando): create, apply, list, get e delete, e toda mudança aceita --dry-run. Os comandos de um reef vivem no seu deck ([O CLI](index.html)).
How does a cluster become a Nereus instance?
Como um cluster vira uma instância do Nereus?
The settings of init, written once to a file
As configurações do init, escritas uma vez num arquivo
# Write the settings, and create nothing$ nereus init \ --create-cluster \ --name nereus-local \ --generate-fileSETTING VALUE SOURCEtarget k3d defaultcreate_cluster true flagname nereus-local flagingress_port 8080 defaultinstallation_name nereus-local cluster nameprofile core default✓ settings written to ~/.config/nereus/init.yaml: edit it, then run 'nereus init'
Two documents (spec 0006): the InitConfig, how to build the platform from this machine, and the Installation, as it goes to the cluster. A plain nereus init reads the file; a flag wins over it, and an unknown key is an error.
The output is from an offline run with a throwaway XDG_CONFIG_HOME, since no walkthrough page records it; the path is shown as it is under the default home.
Dois documentos (spec 0006): o InitConfig, como construir a plataforma desta máquina, e a Installation, como ela vai para o cluster. Um nereus init simples lê o arquivo; uma flag ganha dele, e uma chave desconhecida é um erro.
A saída é de uma execução offline com um XDG_CONFIG_HOME descartável, já que nenhuma página do walkthrough a grava; o caminho aparece como fica no home padrão.
See each setting and where it came from
Veja cada configuração e de onde ela veio
# What init will use, and nothing is created$ nereus init \ --dry-runSETTING VALUE SOURCEtarget k3d defaultcreate_cluster true ~/.config/nereus/init.yamlname nereus-local ~/.config/nereus/init.yamlingress_port 8080 ~/.config/nereus/init.yamlinstallation_name nereus-local ~/.config/nereus/init.yamlprofile core ~/.config/nereus/init.yaml
installation_name is the name the installation gets on its first init, with its id: the metadata.name of the file's Installation, else the cluster name (spec 0006). The dry run also prints the values it would pass to the chart nereus, with the two helm commands that make the same install by hand.
O installation_name é o nome que a instalação recebe no seu primeiro init, com o seu id: o metadata.name da Installation do arquivo, senão o nome do cluster (spec 0006). O dry run também imprime os values que passaria ao chart nereus, com os dois comandos helm que fazem a mesma instalação à mão.
Core in two Helm releases, each step with its time
O core em duas releases do Helm, cada passo com o seu tempo
# Install or upgrade core, from the settings file$ nereus init \ --yesSETTING VALUE SOURCEtarget k3d defaultcreate_cluster true ~/.config/nereus/init.yamlname nereus-local ~/.config/nereus/init.yamlingress_port 8080 ~/.config/nereus/init.yamlinstallation_name nereus-local ~/.config/nereus/init.yamlprofile core ~/.config/nereus/init.yaml✓ prerequisites 0.0s docker 29.9.1, k3d 5.9.0, helm 4.1.4✓ registry localhost:5111 0.0s reused✓ cluster nereus-local 0.1s reused✓ kinds 0.4s release nereus-reefs revision 2✓ nereus 1.1s release nereus revision 2, profile core✓ installation 0.3s kept nereus-local total 1.8s slo 4m, 0% green✓ cluster ready in context k3d-nereus-local · config in ~/.config/nereus/config.yaml · values in ~/.config/nereus/values.yaml
init checks Docker, k3d and Helm first, then creates or reuses the local registry and the k3d cluster, and runs two helm upgrade --installs: kinds (the chart nereus-reefs) and nereus (the Nereus API and the profile core, with the tenancy reef). installation reads back the installation's identity.
Each step prints its time, and the total is measured against the SLO (spec 0004): 8 minutes on k3d; this run on a reused cluster was after nereus config slo set --local 4m ([The time SLO](../../guides/operate/slo.md)). Missing it never stops init; --check-slo fails past the tolerance.
O init confere o Docker, o k3d e o Helm primeiro, depois cria ou reusa o registry local e o cluster k3d, e roda dois helm upgrade --install: kinds (o chart nereus-reefs) e nereus (a API do Nereus e o profile core, com o reef tenancy). O installation lê de volta a identidade da instalação.
Cada passo imprime o seu tempo, e o total é medido contra o SLO (spec 0004): 8 minutos no k3d; esta execução num cluster reusado veio depois de nereus config slo set --local 4m ([O SLO de tempo](../../guides/operate/slo.md)). Perder o SLO nunca para o init; o --check-slo falha passada a tolerância.
A profile after core, installed in the cluster by thetis
Um profile depois do core, instalado no cluster pelo thetis
# Core, then the profile internal-developer-platform$ nereus init \ --profile internal-developer-platform \ --yesSETTING VALUE SOURCEtarget k3d defaultcreate_cluster true ~/.config/nereus/init.yamlname nereus-local ~/.config/nereus/init.yamlingress_port 8080 ~/.config/nereus/init.yamlinstallation_name nereus-local ~/.config/nereus/init.yamlprofile internal-developer-platform flag✓ prerequisites 0.1s docker 29.9.3, k3d 5.9.0, helm 4.1.4✓ registry localhost:5111 0.0s reused✓ cluster nereus-local 16.8s created✓ kinds 0.4s release nereus-reefs revision 1✓ nereus 1.5s release nereus revision 1, profile internal-developer-platform✓ installation 0.2s created nereus-local✓ ready 8m21s 12 Nereids ready, slowest keycloak 2m31s slo 108% red✓ public key 0.0s rsa-4096, SHA256:EyQwfBvDGJkXxcWzg6k5YtiwqRPAHcsv4cvNcH3B0QM, version 1 total 8m40s slo 8m, 108% red✓ cluster ready in context k3d-nereus-local · config in ~/.config/nereus/config.yaml · values in ~/.config/nereus/values.yaml Next steps: nereus status ! init took 8m40s, over its time objective of 8m, within the 20% tolerance (9m36s); slowest steps: ready keycloak 2m31s, ready nereus-portal 2m15s, ready openbao 1m11s; shorten them, or raise the objective: nereus config slo set --local 9m
init runs no step of the profile itself (ADR 0014, profiles): the value profile makes the chart nereus run thetis, the installer Nereid, which installs the profile's reefs, Nereids and Mandates in order. The step ready waits until each Nereid is Ready; public key prints the fingerprint of the secrets reef's key.
--profile reference installs each reef's reference Nereid in place of the tools (#1421); no --profile, or core, installs core alone. An unknown profile is refused before anything changes. With sign-in on, log in right after: nereus status, reef and nereid read through the Nereus API ([nereus login](reefs/authentication.html#login)).
O init não roda nenhum passo do profile (ADR 0014, profiles): o value profile faz o chart nereus rodar o thetis, a Nereid instaladora, que instala os reefs, as Nereids e os Mandates do profile em ordem. O passo ready espera cada Nereid ficar Ready; o public key imprime o fingerprint da chave do reef secrets.
O --profile reference instala a Nereid de referência de cada reef no lugar das ferramentas (#1421); sem --profile, ou com core, instala só o core. Um profile desconhecido é recusado antes de qualquer mudança. Com login ligado, entre logo depois: nereus status, reef e nereid leem pela API do Nereus ([nereus login](reefs/authentication.html#login)).
An undercloud on k3d, and the plan for the cloud
Um undercloud no k3d, e o plano para a nuvem
# The settings file names the cloud azure and the installation tailwind$ nereus init \ --dry-run \ --yes✓ undercloud tailwind-undercloud on k3d 0s✓ installation tailwind, new 0s✓ Reef cloud, Nereid azure 0s Plan for Azure · northeurope · 9 requests · not run (--dry-run) 1 create resource group tailwind-platform 2 create storage account issuers0b7e4c1a93d24f6e 3 create container oidc 4 access Storage Blob Data Contributor on issuers0b7e4c1a93d24f6e to you 5 publish issuer documents (3) 6 create managed identity tailwind-cloud-provisioner 7 create federated credential tailwind-undercloud-azure tagged with the installation and who asked --show-requests for the why, URLs and tags Nothing ran in Azure. To run it:$ nereus init --yes --approve-access
--target <name> creates the installation's undercloud, <installation>-undercloud, with the cloud reef; <name> is that reef's Nereid, here azure, and everything Azure is asked goes through its plans, never a call of the CLI (spec 0005). The issuer is computed from the installation's id before the cluster exists, so the cloud can trust its tokens. --target azure --installation-name tailwind gives the same without a settings file.
What changed on the machine, the plan for the cloud, the command to run next (#379): nothing ran in Azure, but the undercloud, the installation and the cloud reef exist. --show-requests adds each request's why, method, URL and tags. The output is what init prints in its tests (cli/tests/test_undercloud.py), against fakes and recorded Azure answers ([Prepare the undercloud](../../guides/operate/undercloud.md)).
O --target <nome> cria o undercloud da instalação, <instalação>-undercloud, com o reef cloud; <nome> é a Nereid desse reef, aqui a azure, e tudo o que se pede à Azure passa pelos planos dela, nunca por uma chamada do CLI (spec 0005). O issuer é calculado a partir do id da instalação antes de o cluster existir, para que a nuvem possa confiar nos seus tokens. O --target azure --installation-name tailwind dá o mesmo sem arquivo de configurações.
O que mudou na máquina, o plano para a nuvem, o comando a rodar em seguida (#379): nada rodou na Azure, mas o undercloud, a instalação e o reef cloud existem. O --show-requests acrescenta o porquê, o método, a URL e as tags de cada requisição. A saída é a que o init imprime nos seus testes (cli/tests/test_undercloud.py), contra fakes e respostas gravadas da Azure ([Preparar o undercloud](../../guides/operate/undercloud.md)).
The plan approved, each line with its time
O plano aprovado, cada linha com o seu tempo
# Approve the whole run, undercloud included$ nereus init \ --approve-access✓ undercloud tailwind-undercloud on k3d 0s✓ installation tailwind, new 0s✓ Reef cloud, Nereid azure 0s Plan for Azure · northeurope · 9 requests · approved (--approve-access) log: ~/.local/state/nereus/logs/20261019T221500Z-init.log✓ 1 create resource group tailwind-platform 0s✓ 2 create storage account issuers0b7e4c1a93d24f6e 0s✓ 3 create container oidc 0s✓ 4 access Storage Blob Data Contributor on issuers0b7e4c1a93d24f6e to you 0s✓ 5 publish issuer documents (3) 0s✓ 6 create managed identity tailwind-cloud-provisioner 0s✓ 7 create federated credential tailwind-undercloud-azure 0s tagged with the installation and who asked --show-requests for the why, URLs and tags ✓ azure exchanged its token as tailwind-cloud-provisioner Next, a reef that uses the cloud:$ nereus reef apply secrets --from-file ./reefs/secrets/
Without --approve-access, init asks Approve 9 requests? [y/N] under the plan, and a non-interactive run stops before the first request. Once approved, each line shows its progress, then the proof that the cloud trusts the undercloud: the azure Nereid exchanging its token. A request Azure refuses marks its line ✗ and says what an administrator has to run.
A run that sends requests writes a log under ~/.local/state/nereus/logs/, readable by you alone: the plan, each request's method and URL, each answer's status and time; never a token, header or body. Recorded against fakes, as the slide before.
Sem o --approve-access, o init pergunta Approve 9 requests? [y/N] abaixo do plano, e uma execução não interativa para antes da primeira requisição. Depois de aprovado, cada linha mostra o seu progresso, e então a prova de que a nuvem confia no undercloud: a Nereid azure trocando o seu token. Uma requisição que a Azure recusa marca a sua linha com ✗ e diz o que um administrador precisa rodar.
Uma execução que envia requisições grava um log em ~/.local/state/nereus/logs/, legível só por você: o plano, o método e a URL de cada requisição, o status e o tempo de cada resposta; nunca um token, um header ou um corpo. Gravado contra fakes, como o slide anterior.
How is each reef doing?
Como está cada reef?
One row per reef and Nereid, core first
Uma linha por reef e Nereid, o core primeiro
# How each reef is doing, through the Nereus API$ nereus statusREEF NEREID VERSION STATUS AGEauthentication keycloak 0.1.0 Ready 2mcore built-in 0.1.0 Ready 4mrelease flux 0.1.0 Ready 3msecrets openbao 0.1.0 Ready 4mtenancy - - Ready 4m Registry localhost:5111
Registry is where images are pushed, as the cluster declares it in the ConfigMap kube-public/local-registry-hosting (#855). NotConformant is computed by the CLI (spec 0003): a reef that exposes no kind has no Ready Nereid, unless it has none by design; the tenancy reef needs no Nereid and reads Ready.
--output json (or yaml) is the stable contract of the Nereus API's GET /v1/status and of its /mcp status tool: {"installation", "registry", "items": [{"reef", "nereid", "version", "status", "reason", "createdAt"}]}. With sign-in on, it needs nereus login.
O Registry é para onde as imagens são enviadas, como o cluster o declara no ConfigMap kube-public/local-registry-hosting (#855). O NotConformant é calculado pelo CLI (spec 0003): um reef que não expõe kind não tem Nereid Ready, a não ser que não tenha nenhuma por design; o reef tenancy não precisa de Nereid e aparece Ready.
O --output json (ou yaml) é o contrato estável do GET /v1/status da API do Nereus e da ferramenta status do seu /mcp: {"installation", "registry", "items": [{"reef", "nereid", "version", "status", "reason", "createdAt"}]}. Com login ligado, ele precisa do nereus login.
Is this instance healthy?
Esta instância está saudável?
One pass or fail per check, with the command that helps
Um pass ou fail por verificação, com o comando que ajuda
# Ten checks; one that did not run says so$ nereus doctorCHECK RESULT DETAILapi fail no Nereus instance: the CLI does not know its addresscapacity skipped needs apiworkloads skipped needs apinereids skipped needs apistore skipped needs apisecrets skipped needs apiissuer skipped needs apiregistry skipped needs apicli pass nereus and nrs on PATHcompletion pass nereus and nrs in ~/.bash_completions ✗ 1 of 10 checks failed, 7 skipped Next steps: nereus login https://<the instance's address>
The Nereus API is the one door, and it cannot lie (#799, ADR 0018): the cluster's checks run in the API, whose ServiceAccount only reads (GET /v1/doctor); the command adds only what the API cannot see, this machine's CLI and its completion. Only pass counts as passing, and no secret's value is read. --skip <check> leaves one out.
The output is from an offline run with no instance (a throwaway config and no kubeconfig), since no walkthrough page records it: on a running instance every check runs, and a person outside nereus-admins sees the rest without detail.
A API do Nereus é a única porta, e ela não mente (#799, ADR 0018): as verificações do cluster rodam na API, cuja ServiceAccount só lê (GET /v1/doctor); o comando acrescenta só o que a API não vê, o CLI desta máquina e o seu completion. Só pass conta como aprovado, e nenhum valor de secret é lido. O --skip <check> deixa uma de fora.
A saída é de uma execução offline sem instância (uma config descartável e sem kubeconfig), já que nenhuma página do walkthrough a grava: numa instância rodando, toda verificação roda, e uma pessoa fora de nereus-admins vê o resto sem detalhe.
The version of this nereus, as --version prints it
A versão deste nereus, como o --version a imprime
# The same line as nereus --version$ nereus versionnereus 0.1.31 # As data, for scripts and agents$ nereus version \ --output json{ "name": "nereus", "version": "0.1.31"}
nereus version and nereus --version print the same (#1868), in every --output format (#1624). The version comes from the git tag (#186).
nereus version e nereus --version imprimem o mesmo (#1868), em todo formato de --output (#1624). A versão vem da tag do git (#186).
How does a capability arrive?
Como uma capacidade chega?
A reef applied from the version this CLI pins
Um reef aplicado da versão que este CLI fixa
# Apply the reef release, with its kinds$ nereus reef apply release✓ core/reefs/release 0.1.0 created (release.getnereus.dev/v1alpha1: releases, repositories, sources, targets) Next steps: nereus release --help nereus nereid apply <nereid> --reef release # Again: no resourceVersion moved$ nereus reef apply releasecore/reefs/release unchanged
A Nereid needs its reef first: without it, nereid apply is refused with Apply it first: nereus reef apply release. Once the reef exists, the CLI has a release group, empty until a Nereid is applied.
unchanged when no resourceVersion moved, as kubectl apply does. Every document is checked first: only CustomResourceDefinitions of the reef's own group, never a platform kind.
Uma Nereid precisa do seu reef antes: sem ele, o nereid apply é recusado com Apply it first: nereus reef apply release. Assim que o reef existe, o CLI tem um grupo release, vazio até uma Nereid ser aplicada.
unchanged quando nenhum resourceVersion mudou, como faz o kubectl apply. Todo documento é conferido antes: só CustomResourceDefinitions do grupo do próprio reef, nunca um kind da plataforma.
A reef from local YAML, previewed first
Um reef de YAML local, visto antes
# What would change, and nothing changes$ nereus reef apply cloud \ --dry-runKIND NAME CHANGECustomResourceDefinition clouds.cloud.getnereus.dev createReef cloud createNothing changed (--dry-run). # From a folder of YAML$ nereus reef apply cloud \ --from-file ./cloud/✓ core/reefs/cloud 0.1.0 configured (cloud.getnereus.dev/v1alpha1: clouds)
apply creates or updates from three sources: the version the CLI pins, local YAML (--from-file, a file or a folder; alias --path) or a reef package (--image, an OCI artifact of YAML layers). configured when the files changed a kind; the same files again report unchanged.
O apply cria ou atualiza de três fontes: a versão que o CLI fixa, YAML local (--from-file, um arquivo ou uma pasta; alias --path) ou um pacote de reef (--image, um artefato OCI de camadas YAML). configured quando os arquivos mudaram um kind; os mesmos arquivos de novo dão unchanged.
create fails on a reef that exists, and says what changes it
O create falha num reef que existe, e diz o que o muda
# As kubectl create does$ nereus reef create release✗ reef release already exists. To change it, run one of: nereus reef apply release # the version this CLI pins nereus reef apply release --image <ref> # an OCI package nereus reef apply release --from-file <file or folder>
On a new reef, create prints the same line as apply, core/reefs/<reef> <version> created, from the version this CLI pins; on one that exists it fails and names the three ways to change it. It takes --dry-run.
Num reef novo, o create imprime a mesma linha do apply, core/reefs/<reef> <version> created, da versão que este CLI fixa; num que existe ele falha e nomeia as três formas de mudá-lo. Ele aceita --dry-run.
Each reef with the Nereids that look after it
Cada reef com as Nereids que cuidam dele
# Every reef$ nereus reef listREEF NEREIDSrelease -secrets openbao
reef list and reef get read through the Nereus API at the instance's URL, with the token of nereus login, so they need no kubeconfig; only a member of nereus-admins reads them. - is a reef no Nereid looks after yet.
O reef list e o reef get leem pela API do Nereus na URL da instância, com o token do nereus login, então não precisam de kubeconfig; só um membro de nereus-admins os lê. - é um reef de que nenhuma Nereid cuida ainda.
One reef in full: its group, kinds, Nereids and Mandates
Um reef por inteiro: grupo, kinds, Nereids e Mandates
# The reef release, with its reference Nereid$ nereus reef get releaseName: releaseGroup: release.getnereus.dev/v1alpha1Version: 0.1.0Kinds: Release, Repository, Source, TargetNereids: reference-releaseMandates: reference (default)Age: 2m
A reef with no Nereid ends with the Next steps: line nereus nereid apply <nereid> --reef <reef>; one the API keeps by design, as tenancy, says none needed: the API keeps its objects.
The output is taken from the code (cli/src/nereus/commands/reef.py, its test in cli/tests/test_commands.py), not a recorded run: no walkthrough page records reef get yet.
Um reef sem Nereid termina com a linha de Next steps: nereus nereid apply <nereid> --reef <reef>; um que a API guarda por design, como o tenancy, diz none needed: the API keeps its objects.
A saída é tirada do código (cli/src/nereus/commands/reef.py, o seu teste em cli/tests/test_commands.py), não de uma execução gravada: nenhuma página do walkthrough grava o reef get ainda.
With no Nereid left, the reef and its group go
Sem Nereid restante, o reef e o seu grupo vão embora
# Delete the reef; its kinds stay$ nereus reef delete release✓ core/reefs/release deleted
reef delete removes the Reef object and keeps its kinds, so a Nereid's objects stay. It is refused while a Nereid of it is applied, and names the nereid delete to run first. It takes --dry-run.
O reef delete remove o objeto Reef e mantém os seus kinds, então os objetos de uma Nereid ficam. Ele é recusado enquanto uma Nereid dele estiver aplicada, e nomeia o nereid delete a rodar antes. Ele aceita --dry-run.
Who looks after a reef?
Quem cuida de um reef?
A Nereid from its image, pinned to the digest
Uma Nereid da sua imagem, fixada pelo digest
# Apply the reference Nereid to the reef release$ nereus nereid apply reference-release \ --reef release \ --image localhost:5111/reference-release-controller:0.1.0✓ core/nereids/reference-release created, Ready, pinned to sha256:ffb8e8957c6e: see 'nereus release --help' Next steps: nereus nereid list
The CLI reads the image's labels in the registry (manifest and config, no layer): name, reef, required reefs, version. It checks the reef exists, writes the Nereid object pinned to the digest, and runs the image as its controller, which reports Ready. The tag is resolved once, so pushing it again never changes what runs.
A name argument wins over the label, and --reef repeats. An image that declares no reef is refused unless --reef names one; a Nereid whose required reef has no Nereid is refused too ([Require a reef](../../guides/build/requires.md)).
O CLI lê os labels da imagem no registry (manifest e config, nenhuma camada): nome, reef, reefs exigidos, versão. Ele confere que o reef existe, escreve o objeto Nereid fixado pelo digest, e roda a imagem como o seu controller, que reporta Ready. A tag é resolvida uma vez, então publicá-la de novo nunca muda o que roda.
Um argumento de nome ganha do label, e o --reef se repete. Uma imagem que não declara reef é recusada, a não ser que o --reef nomeie um; uma Nereid cujo reef exigido não tem Nereid também é recusada ([Exigir um reef](../../guides/build/requires.md)).
Another image updates it in place, with no delete
Outra imagem a atualiza no lugar, sem delete
# What would change$ nereus nereid apply reference-release \ --image localhost:5111/reference-release-controller:0.1.1 \ --dry-runWould configure core/nereids/reference-release for reef release: image sha256:ffb8e8957c6e → sha256:3f2a9c1d7e4b.Nothing changed (--dry-run). # The new image$ nereus nereid apply reference-release \ --image localhost:5111/reference-release-controller:0.1.1✓ core/nereids/reference-release configured, Ready, pinned to sha256:3f2a9c1d7e4b (was sha256:ffb8e8957c6e): see 'nereus release --help'
Its rules, its Deployment and its record move together, and the apply ends once the new pod runs (#386). The same image again reports unchanged; a new image that fails prints the nereus nereid apply line with the last image that worked.
As suas regras, o seu Deployment e o seu registro mudam juntos, e o apply termina quando o pod novo roda (#386). A mesma imagem de novo dá unchanged; uma imagem nova que falha imprime a linha do nereus nereid apply com a última imagem que funcionou.
Only the endpoints a person grants are ever published
Só os endpoints que uma pessoa concede são publicados
# Let the edge reef publish Triton's mcp endpoint$ nereus nereid apply triton \ --publish mcp✓ core/nereids/triton unchanged, Ready✓ core/nereids/triton configured (publishes: mcp) # Take the grant away$ nereus nereid apply triton \ --publish ""✓ core/nereids/triton unchanged, Ready✓ core/nereids/triton configured (publishes nothing)
The grant is the Nereid's spec.publish (#1951, OWASP A01): an endpoint its status lists is published by the edge reef only when it is publishable and named here. The names given replace the grant; without --publish an apply leaves it as it is. Each name is checked before anything is written.
A concessão é o spec.publish da Nereid (#1951, OWASP A01): um endpoint que o seu status lista só é publicado pelo reef edge quando é publicável e está nomeado aqui. Os nomes dados substituem a concessão; sem --publish um apply a deixa como está. Cada nome é verificado antes de qualquer escrita.
create is apply that fails when the Nereid exists
O create é o apply que falha quando a Nereid existe
# A new Nereid, from flags$ nereus nereid create reference-release \ --reef release \ --image localhost:5111/reference-release-controller:0.1.0✓ core/nereids/reference-release created, Ready, pinned to sha256:ffb8e8957c6e: see 'nereus release --help' Next steps: nereus nereid list # Again: it exists, and the line names apply$ nereus nereid create reference-release \ --reef release✗ nereid reference-release already exists (reef: release). To change it, run: nereus nereid apply reference-release --reef release
As kubectl create does (ADR 0013): create takes the options of nereid apply and waits for the Nereid to report Ready, but refuses one that exists.
The output is taken from the code (cli/src/nereus/commands/nereid.py: the first line is nereid apply's, the second its refusal), not a recorded run.
Como faz o kubectl create (ADR 0013): o create aceita as opções do nereid apply e espera a Nereid reportar Ready, mas recusa uma que existe.
A saída é tirada do código (cli/src/nereus/commands/nereid.py: a primeira linha é a do nereid apply, a segunda a sua recusa), não de uma execução gravada.
Each Nereid with its reefs, image and status
Cada Nereid com os seus reefs, imagem e status
# Every Nereid$ nereus nereid listNEREID REEFS IMAGE STATUS AGEreference-release release localhost:5111/reference-release-controller:0.1.0 Ready 10sopenbao secrets localhost:5111/openbao-controller:0.1.0 Ready 1m
REEFS lists every reef the Nereid looks after; IMAGE is the repository and version. Unavailable is computed by the CLI from the Deployment (spec 0003), as when the controller is scaled to zero. With none, it prints No nereids added.; with sign-in on, it reads through the Nereus API.
O REEFS lista todo reef de que a Nereid cuida; o IMAGE é o repositório e a versão. O Unavailable é calculado pelo CLI a partir do Deployment (spec 0003), como quando o controller está escalado para zero. Sem nenhuma, imprime No nereids added.; com login ligado, lê pela API do Nereus.
One Nereid in full, with its Mandates
Uma Nereid por inteiro, com os seus Mandates
# The keycloak Nereid$ nereus nereid get keycloakName: keycloakReefs: authenticationImage: localhost:5111/keycloak-controller:0.1.0Digest: sha256:0f4675ab231b4e6d4a439d0c7d8e5b07011f35802b38592851542cf56666be93Title: authentication-keycloak-controllerDescription: The keycloak Nereid of Nereus, for the authentication reefStatus: ReadyMandates: keycloak (default)Age: 2m
The pinned digest, the image's title and description, and the Mandates naming it. A Nereid that is not Ready shows its Reason, such as NotConformant.
O digest fixado, o título e a descrição da imagem, e os Mandates que a nomeiam. Uma Nereid que não está Ready mostra o seu Reason, como NotConformant.
Its commands and everything it ran go with it
Os seus comandos e tudo o que ela rodava vão junto
# The last Nereid of a reef another Nereid requires$ nereus nereid delete reference-release✗ reference-release is the last Nereid of reef release, which added Nereids require: reference-docs. Remove them first, or go ahead with: nereus nereid delete reference-release --force # With nothing requiring it$ nereus nereid delete reference-release✓ core/nereids/reference-release deleted
The Deployment, Service and identity belong to the Nereid object, so they go too; the reef stays, and its group says no Nereid added. The first run is from [Require a reef](../../guides/build/requires.md), with reference-docs applied; --force deletes it anyway. It takes --dry-run.
O Deployment, o Service e a identidade pertencem ao objeto Nereid, então vão também; o reef fica, e o seu grupo diz no Nereid added. A primeira execução é de [Exigir um reef](../../guides/build/requires.md), com reference-docs aplicada; o --force a apaga mesmo assim. Ele aceita --dry-run.
Which Nereid answers, and with which settings?
Qual Nereid responde, e com quais configurações?
A GitHub App is a Mandate of the github Nereid
Um GitHub App é um Mandate do Nereid github
# The App's identity, bound to the reef$ nereus mandate create github \ --reef authentication \ --nereid github \ --param appId=123456 \ --param privateKey=github-app-key \ --param allow=nereus-system:*:contents=read \ --param allow=example:example/app:metadata=read \ --default✓ core/mandates/github created (reef: authentication, nereid: github, default) clusterrole/controller-github configured (nereid github writes the status of mandate github) Next steps: nereus mandate list
A Mandate binds a reef to the Nereid that fulfils it, with its params (ADR 0011); --default makes it the reef's default, and the CLI lets the Nereid write its status (#406). Moved here from the authentication reef's deck (#482), where the App's private key was first stored as a plain secret, github-app-key ([nereus secrets create](reefs/secrets.html#create) with --from-env GITHUB_APP_KEY).
No --vendor and no Application kind (owner, 2026-11-09): the model of ADR 0011 holds, and github appears only in nereid apply and mandate create, never in a reef's command. The Nereid is opt-in (nereus nereid apply github --reef authentication --reef scm), outside the internal-developer-platform profile. It reads the key through a SecretBinding in its own namespace (ADR 0023's pattern). A second App is a second Mandate, chosen with --mandate. allow says who may ask it a token (#1287): <namespace>:<repository or *>:<permission>=<level>[,...], repeated (the CLI joins a repeated --param with ;); with none, no token is minted (deny by default).
Um Mandate liga um reef à Nereid que o cumpre, com os seus params (ADR 0011); o --default o torna o padrão do reef, e o CLI deixa a Nereid escrever o seu status (#406). Movido para cá do deck do reef authentication (#482), onde a chave privada do App foi guardada antes como um secret simples, github-app-key ([nereus secrets create](reefs/secrets.html#create) com --from-env GITHUB_APP_KEY).
Sem --vendor e sem kind Application (dono, 2026-11-09): o modelo do ADR 0011 vale, e github aparece só no nereid apply e no mandate create, nunca num comando de reef. O Nereid é opcional (nereus nereid apply github --reef authentication --reef scm), fora do profile internal-developer-platform. Ele lê a chave por um SecretBinding no seu próprio namespace (o padrão do ADR 0023). Um segundo App é um segundo Mandate, escolhido com --mandate. O allow diz quem pode lhe pedir um token (#1287): <namespace>:<repositório ou *>:<permissão>=<nível>[,...], repetido (a CLI junta um --param repetido com ;); sem nenhum, nenhum token é emitido (negado por padrão).
apply creates or changes a Mandate's params
O apply cria ou muda os params de um Mandate
# The portal's public address, in its Mandate$ nereus mandate apply nereus-portal \ --reef portal \ --nereid nereus-portal \ --param publicUrl=https://portal.example.com✓ core/mandates/nereus-portal configured (reef: portal, nereid: nereus-portal, default) Next steps: nereus mandate list
The reef and the Nereid never change; the params and --default do. A Mandate that becomes the default prints the one that is no longer the default under it. The output is from the portal reef's deck ([nereus mandate apply](reefs/portal.html)). It takes --dry-run.
O reef e a Nereid nunca mudam; os params e o --default sim. Um Mandate que vira o padrão imprime embaixo o que deixou de ser o padrão. A saída é do deck do reef portal ([nereus mandate apply](reefs/portal.html)). Ele aceita --dry-run.
A second Mandate of a reef, then the list
Um segundo Mandate de um reef, depois a lista
# Another Mandate of the same reef and Nereid$ nereus mandate create corporate \ --reef authentication \ --nereid keycloak✓ core/mandates/corporate created (reef: authentication, nereid: keycloak) clusterrole/controller-keycloak configured (nereid keycloak writes the status of mandate corporate) Next steps: nereus mandate list # Every Mandate$ nereus mandate listMANDATE REEF NEREID DEFAULT STATUS AGEcorporate authentication keycloak false Ready 3sdefault secrets openbao true Ready 1mkeycloak authentication keycloak true Ready 11s
After nereus login, nereus mandate goes through the Nereus API, for a person in nereus-admins, with no kubeconfig (#1323). --default would make corporate the reef's default.
Depois do nereus login, o nereus mandate passa pela API do Nereus, para uma pessoa em nereus-admins, sem kubeconfig (#1323). O --default tornaria o corporate o padrão do reef.
The Mandate's status says what the App may do
O status do Mandate diz o que o App pode fazer
# What the Nereid wrote, in the Mandate's status$ nereus mandate get githubName: githubReef: authenticationNereid: githubDefault: trueParams: allow=nereus-system:*:contents=read;example:example/app:metadata=read, appId=123456, privateKey=github-app-keyStatus: ReadyApp: example-nereusInstallations: example (all repositories)Permissions: contents=read, metadata=readAge: 10sAllowed: NAMESPACE REPOSITORY PERMISSIONS nereus-system * contents=read example example/app metadata=read
Every Mandate shows its reef, Nereid, params and status; the rest is what its Nereid wrote. Moved here from the authentication reef's deck (#482).
There is no verify command: the status is Ready, NotRegistered (no App yet: [app-register](reefs/authentication.html#app-register)), NotInstalled (with the install URL in its message), InvalidCredentials, MissingParam or InvalidParam (an allow entry that does not parse, #1287). Permissions start at metadata and contents read (owner, 2026-11-09). The App's one webhook takes its secret from the param webhookSecret and points at the scm reef's receiver (ADR 0024).
Todo Mandate mostra o seu reef, Nereid, params e status; o resto é o que a sua Nereid escreveu. Movido para cá do deck do reef authentication (#482).
Não há comando verify: o status é Ready, NotRegistered (sem App ainda: [app-register](reefs/authentication.html#app-register)), NotInstalled (com a URL de instalação na mensagem), InvalidCredentials, MissingParam ou InvalidParam (uma entrada de allow que não se lê, #1287). As permissões começam em leitura de metadata e contents (dono, 2026-11-09). O único webhook do App tira o seu secret do param webhookSecret e aponta para o receptor do reef scm (ADR 0024).
The reef and the Nereid stay; its grant goes first
O reef e a Nereid ficam; a sua permissão sai antes
# Delete the second Mandate$ nereus mandate delete corporate✓ core/mandates/corporate deleted (reef: authentication, nereid: keycloak) clusterrole/controller-keycloak configured (nereid keycloak no longer writes the status of mandate corporate) Next steps: nereus mandate list
The Nereid's grant goes first, so a failed run deletes nothing and runs again (#706). When it was its reef's default, the reef has none until another Mandate takes it, and the Next steps: name the mandate apply ... --default to run. It takes --dry-run.
The output is taken from the code (cli/src/nereus/commands/mandate.py), not a recorded run.
A permissão da Nereid sai antes, então uma execução que falha não apaga nada e roda de novo (#706). Quando ele era o padrão do reef, o reef fica sem padrão até outro Mandate assumir, e os Next steps: nomeiam o mandate apply ... --default a rodar. Ele aceita --dry-run.
A saída é tirada do código (cli/src/nereus/commands/mandate.py), não de uma execução gravada.
Which reefs and Nereids come together?
Quais reefs e Nereids vêm juntos?
Four profiles, built in, core the default
Quatro profiles, embutidos, o core o padrão
# Every profile and its Nereids$ nereus profile listNAME NEREIDS INGRESS DEFAULTcore - - trueinternal-developer-platform openbao, flux, cloudnative-pg, keycloak, nereus-portal, victoriametrics, vcluster, catalog, kubernetes, zot, buildkit, forgejo istioreference reference-secrets, reference-release -secrets openbao -
A profile is a set of reefs, Nereids and Mandates that come together (ADR 0014). Profiles are built in; profile create is not built yet.
Um profile é um conjunto de reefs, Nereids e Mandates que vêm juntos (ADR 0014). Os profiles são embutidos; o profile create ainda não está pronto.
What a profile installs, in the order of its images
O que um profile instala, na ordem das suas imagens
# The Nereids, their reefs and Mandates, and who requires each$ nereus profile describe internal-developer-platformIngress: Gateway API v1.7.0, Istio 1.30.4 (Gateway istio-system/ingress) NEREID REEF MANDATE REQUIRED BYopenbao secrets default (default) keycloak, forgejoflux release flux (default) cloudnative-pg, keycloak, victoriametrics, vcluster, kubernetes, zot, forgejocloudnative-pg database cloudnative-pg (default) keycloakkeycloak authentication keycloak (default) nereus-portalnereus-portal portal nereus-portal (default) -victoriametrics metrics victoriametrics (default) -vcluster environment vcluster (default) kubernetescatalog catalog catalog (default) kubernetes, buildkitkubernetes delivery kubernetes (default) -zot registry zot (default) buildkitbuildkit build buildkit (default) -forgejo scm forgejo (default) -
The order comes from each Nereid's image, its label core.getnereus.dev/requires (#1368). With no registry answering, describe prints the same order from the offline list cli/src/nereus/requires.yaml and ends with a line that says so.
A ordem vem da imagem de cada Nereid, o seu label core.getnereus.dev/requires (#1368). Sem registry respondendo, o describe imprime a mesma ordem da lista offline cli/src/nereus/requires.yaml e termina com uma linha que diz isso.
A profile on top of core, from the laptop, one line per step
Um profile sobre o core, do laptop, uma linha por passo
# Again, on a cluster that has it: every line unchanged$ nereus profile apply internal-developer-platform✓ reef secrets 0.1s core/reefs/secrets 0.1.0 unchanged (secrets.getnereus.dev/v1alpha1: secrets, secretbindings, vaults)✓ nereid openbao 1.2s core/nereids/openbao unchanged, Ready✓ mandate default 0.0s core/mandates/default unchanged (reef: secrets, nereid: openbao, default)✓ public key 0.0s rsa-4096, SHA256:szPWBVj2le3/W+vbmlx8oEAHRBvXP29a3qyYDM4LTnA, version 1✓ vault default 0.0s secrets/vaults/default unchanged (mandate: default)✓ reef release 0.1s core/reefs/release 0.1.0 unchanged (release.getnereus.dev/v1alpha1: releases, repositories, sources, targets)✓ flux 0.6s flux/v2.9.6 unchanged (source-controller, helm-controller in namespace flux-system)✓ nereid flux 0.2s core/nereids/flux unchanged, Ready✓ mandate flux 0.0s core/mandates/flux unchanged (reef: release, nereid: flux, default)✓ reef database 0.0s core/reefs/database 0.1.0 unchanged (database.getnereus.dev/v1alpha1: databases)✓ nereid cloudnative-pg 0.3s core/nereids/cloudnative-pg unchanged, Ready✓ mandate cloudnative-pg 0.0s core/mandates/cloudnative-pg unchanged (reef: database, nereid: cloudnative-pg, default)✓ reef authentication 0.0s core/reefs/authentication 0.1.0 unchanged (authentication.getnereus.dev/v1alpha1: tokens)✓ nereid keycloak 0.1s core/nereids/keycloak unchanged, Ready✓ mandate keycloak 0.7s core/mandates/keycloak unchanged (reef: authentication, nereid: keycloak, default)✓ gateway-api 1.3s gateway-api/v1.7.0 unchanged (the Gateway API CRDs)✓ repository istio 0.0s release/repositories/istio unchanged✓ source istio-base 0.0s release/sources/istio-base unchanged✓ source istiod 0.0s release/sources/istiod unchanged✓ source istio-gateway 0.0s release/sources/istio-gateway unchanged✓ target istio-system 0.0s release/targets/istio-system unchanged✓ release istio-base 0.7s release/releases/istio-base unchanged (nereid: flux)✓ release istiod 0.0s release/releases/istiod unchanged (nereid: flux)✓ release istio-gateway 0.0s release/releases/istio-gateway unchanged (nereid: flux)✓ gateway ingress 0.0s istio-system/ingress unchanged✓ reef portal 0.0s core/reefs/portal unchanged (portal.getnereus.dev/v1alpha1)✓ nereid nereus-portal 0.3s core/nereids/nereus-portal unchanged, Ready✓ mandate nereus-portal 0.0s core/mandates/nereus-portal unchanged (reef: portal, nereid: nereus-portal, default)✓ reef metrics 0.0s core/reefs/metrics unchanged (metrics.getnereus.dev/v1alpha1)✓ networkpolicy vmsingle-nereus 0.0s networkpolicies/vmsingle-nereus applied (only vmagent-nereus and nereus-api reach vmsingle-nereus)✓ nereid victoriametrics 0.1s core/nereids/victoriametrics unchanged, Ready✓ mandate victoriametrics 0.0s core/mandates/victoriametrics unchanged (reef: metrics, nereid: victoriametrics, default)✓ reef environment 0.0s core/reefs/environment 0.1.0 unchanged (environment.getnereus.dev/v1alpha1: environments)✓ nereid vcluster 0.1s core/nereids/vcluster unchanged, Ready✓ mandate vcluster 0.0s core/mandates/vcluster unchanged (reef: environment, nereid: vcluster, default)✓ reef catalog 0.1s core/reefs/catalog unchanged (catalog.getnereus.dev/v1alpha1: packages, packagetypes, workloads, workloadtypes)✓ nereid catalog 0.1s core/nereids/catalog unchanged, Ready✓ mandate catalog 0.0s core/mandates/catalog unchanged (reef: catalog, nereid: catalog, default)✓ reef delivery 0.0s core/reefs/delivery unchanged (delivery.getnereus.dev/v1alpha1: deliveries)✓ nereid kubernetes 0.1s core/nereids/kubernetes unchanged, Ready✓ mandate kubernetes 0.0s core/mandates/kubernetes unchanged (reef: delivery, nereid: kubernetes, default)✓ reef registry 0.0s core/reefs/registry unchanged (registry.getnereus.dev/v1alpha1: registries, repositories)✓ nereid zot 0.1s core/nereids/zot unchanged, Ready✓ mandate zot 0.0s core/mandates/zot unchanged (reef: registry, nereid: zot, default)✓ reef build 0.0s core/reefs/build unchanged (build.getnereus.dev/v1alpha1: builds)✓ namespace builds 0.2s namespaces/builds applied (Pod Security privileged, push credentials from the registry, the buildkit Nereid's Role, an admission policy on its Jobs and Pods, and one on Builds with no owner); namespaces/builds-egress applied (the egress proxy smokescreen, the only way out of a build's RUN)✓ nereid buildkit 0.1s core/nereids/buildkit unchanged, Ready✓ mandate buildkit 0.0s core/mandates/buildkit unchanged (reef: build, nereid: buildkit, default)✓ reef scm 0.0s core/reefs/scm unchanged (scm.getnereus.dev/v1alpha1: connections, mirrors)✓ namespace nereus-system-forgejo 0.1s namespaces/nereus-system-forgejo applied (the forgejo Nereid's Role there, for Forgejo's admin)✓ nereid forgejo 0.1s core/nereids/forgejo unchanged, Ready✓ mandate forgejo 0.0s core/mandates/forgejo unchanged (reef: scm, nereid: forgejo, default) total 6.4s Next steps: nereus reef list nereus nereid list
profile apply runs the same steps thetis runs (#425), from the laptop, one line each; on a cluster with core alone each line says created, and applying again reports every line unchanged, as here. --without buildkit leaves a Nereid out (#1231); --dry-run lists the steps and changes nothing. On a cluster init has not prepared, it stops and points to nereus init.
O profile apply roda os mesmos passos que o thetis (#425), do laptop, uma linha cada; num cluster só com o core cada linha diz created, e aplicar de novo dá unchanged em toda linha, como aqui. O --without buildkit deixa uma Nereid de fora (#1231); o --dry-run lista os passos e não muda nada. Num cluster que o init não preparou, ele para e aponta para o nereus init.
Which settings does the platform keep?
Quais configurações a plataforma guarda?
Your current owner, in the CLI's own config
O seu owner atual, na config do próprio CLI
# The node the next commands are for$ nereus config set owner project/triton✓ config: owner = Project/triton
The one setting of the person, not of the platform (ADR 0016, #902): kept in ~/.config/nereus/config.yaml, never the kubeconfig. The owner must exist in the tenancy tree; a command with no --owner uses it, and its output names the owner used ([The tenancy reef](reefs/tenancy.html#config-owner)).
A única configuração da pessoa, não da plataforma (ADR 0016, #902): guardada em ~/.config/nereus/config.yaml, nunca no kubeconfig. O owner precisa existir na árvore do tenancy; um comando sem --owner o usa, e a sua saída nomeia o owner usado ([O reef tenancy](reefs/tenancy.html#config-owner)).
Read it back, with no cluster
Leia de volta, sem cluster
# The current owner$ nereus config get ownerProject/triton # None set: the line says how$ nereus config get owner✗ owner is not set: nereus config set owner project/<name>
config get reads only the CLI's own config, so it answers with no cluster. The output is from an offline run with a throwaway XDG_CONFIG_HOME.
O config get lê só a config do próprio CLI, então responde sem cluster. A saída é de uma execução offline com um XDG_CONFIG_HOME descartável.
The SLO of init, from the cluster or its default
O SLO do init, do cluster ou o seu padrão
# Each value and where it came from$ nereus config slo showSETTING VALUE SOURCElocal 8m defaultcloud 20m defaultyellow 50% defaultorange 75% defaultred 100% defaulttolerance 20% default
The service level objective of init (SLO, spec 0004): 8 minutes on k3d, 20 on a cloud (recorded, not checked yet). yellow, orange and red are the shares of the objective where the clock changes colour; tolerance is how far past it init --check-slo still passes. The cluster may override them in one ServiceLevelObjective object in nereus-system.
O objetivo de nível de serviço do init (SLO, spec 0004): 8 minutos no k3d, 20 numa nuvem (gravado, ainda não conferido). yellow, orange e red são as frações do objetivo em que o relógio muda de cor; tolerance é quanto além dele o init --check-slo ainda passa. O cluster pode sobrescrevê-los num objeto ServiceLevelObjective em nereus-system.
Change some values; the rest keep their defaults
Mude alguns valores; o resto mantém o seu padrão
# A tighter objective on k3d, and a smaller tolerance$ nereus config slo set \ --local 4m \ --tolerance 5SETTING VALUE SOURCElocal 4m clustercloud 20m defaultyellow 50% defaultorange 75% defaultred 100% defaulttolerance 5% cluster
Written to the cluster, read by every init on it, in its last step. Past the objective, every init warns with the slowest steps and the config slo set that raises it.
Gravado no cluster, lido por todo init nele, no seu último passo. Passado o objetivo, todo init avisa com os passos mais lentos e o config slo set que o aumenta.
Back to the defaults
De volta aos padrões
# Delete the SLO from the cluster$ nereus config slo reset✓ SLO reset: every value is back to its default
With no SLO in the cluster, it says every value is already its default.
Sem SLO no cluster, ele diz que todo valor já é o seu padrão.
Every installation has a name, an id and an alias
Toda instalação tem um nome, um id e um alias
# This installation$ nereus config installation showNAME ALIAS IDnereus-local nereus-local 04d6e336-7dcb-42ab-926a-2595099d5336
The name and the id never change (spec 0006): the name prefixes every name the platform creates outside itself, and the id is a random UUID that cloud resources can carry. The alias is what listings show. The first init creates them in one Installation object in nereus-system, and writes the id to the settings file, so a cluster recreated from it is the same installation.
O nome e o id nunca mudam (spec 0006): o nome prefixa todo nome que a plataforma cria fora de si, e o id é um UUID aleatório que os recursos de nuvem podem levar. O alias é o que as listagens mostram. O primeiro init os cria num objeto Installation em nereus-system, e grava o id no arquivo de configurações, então um cluster recriado dele é a mesma instalação.
Change the alias or a naming override; name and id stay
Mude o alias ou um naming override; nome e id ficam
# A new alias$ nereus config installation set \ --alias "Acme Prod"✓ installation nereus-local alias = Acme Prod✓ file ~/.config/nereus/init.yaml updated # A name instead of a generated one that is taken$ nereus config installation set \ --naming-override issuer.storage=acmeissuers01✓ installation nereus-local naming.overrides.issuer.storage = acmeissuers01✓ file ~/.config/nereus/init.yaml updated
Each change goes to the Installation object and to the settings file it came from. An alias is free text of at most 63 characters; an override (issuer.storage, state.storage or secrets.vault) is checked against its resource's rules, and names a resource to create, never to rename: once the issuer is published, a new name is refused (spec 0005).
Cada mudança vai para o objeto Installation e para o arquivo de configurações de onde ele veio. Um alias é texto livre de até 63 caracteres; um override (issuer.storage, state.storage ou secrets.vault) é conferido contra as regras do seu recurso, e nomeia um recurso a criar, nunca a renomear: com o issuer publicado, um nome novo é recusado (spec 0005).
Which tools does claude.ai get?
Quais ferramentas o claude.ai recebe?
The tools the reefs offer at /mcp, each on or off
As ferramentas que os reefs oferecem em /mcp, cada uma ligada ou desligada
# The tools you may call, the core's status first$ nereus mcp tool listREEF TOOL STATEcore status onpresentations presentations_list onpresentations presentations_share off (write)
Each reef declares its tools in its Nereid's contract, and the Nereus API serves them at /mcp (ADR 0029). A row shows only a tool whose route you may call. off (write) is a tool whose route is a POST: it starts off until an admin enables it; off (instance) is one an admin turned off. Only the tools on reach claude.ai.
Cada reef declara suas ferramentas no contrato da sua Nereid, e a API do Nereus as serve em /mcp (ADR 0029). Uma linha mostra só uma ferramenta cuja rota você pode chamar. off (write) é uma ferramenta cuja rota é um POST: ela começa desligada até um admin habilitá-la; off (instance) é uma que um admin desligou. Só as ferramentas on chegam ao claude.ai.
An admin chooses which tools the instance offers
Um admin escolhe quais ferramentas a instância oferece
# Stop offering one tool$ nereus mcp tool disable presentations_list✓ tool presentations_list disabled for the instance # Offer every tool of a reef; the name above still wins$ nereus mcp tool enable 'presentations_*'✓ tools presentations_* enabled for the instance! presentations_list stays off: disabled by its own name, which beats a pattern
The switch lives in the Installation's spec.mcp.tools, written by the Nereus API for a person in nereus-admins, so its log names who turned what on or off; anyone else gets the refusal naming the group. A rule is a tool name or <reef>_*; an exact name beats a pattern, and within one, disabled wins. A model never changes it: the API refuses the call when it comes through /mcp.
O switch fica no spec.mcp.tools do Installation, gravado pela API do Nereus para uma pessoa em nereus-admins, então o log dela diz quem ligou ou desligou o quê; qualquer outra pessoa recebe a recusa que nomeia o grupo. Uma regra é um nome de ferramenta ou <reef>_*; um nome exato vence um padrão, e dentro de um, disabled vence. Um modelo nunca o muda: a API recusa a chamada quando ela vem por /mcp.
The instance's /mcp in Claude Code, with one command
O /mcp da instância no Claude Code, com um comando
# Add the instance's MCP server to Claude Code$ nereus mcp client add claude-code✓ claude-code: MCP server nereus added (https://nereus.example.com/mcp, scope user, OAuth client claude-code) Next steps: claude # then /mcp, and log in to nereus # The coding agents that have it$ nereus mcp client listCLIENT SERVER URL SCOPEclaude-code nereus https://nereus.example.com/mcp user
It runs the agent's own CLI (claude mcp add | get | remove), never writes its settings and never copies your token: Claude Code logs in for aud: nereus-mcp itself (#1880). The OAuth client claude-code and its fixed callback port come from the instance's /.well-known/nereus-configuration, since Claude Code listens on http://localhost:<port>/callback and the realm accepts only that exact address.
Ele roda o CLI do próprio agente (claude mcp add | get | remove), nunca escreve as configurações dele e nunca copia o seu token: o Claude Code faz login para aud: nereus-mcp sozinho (#1880). O client OAuth claude-code e sua porta fixa de callback vêm do /.well-known/nereus-configuration da instância, já que o Claude Code escuta em http://localhost:<porta>/callback e o realm aceita só esse endereço exato.