Docs
siDiscord

Secrets

Secrets are the keys and credentials a service sends to other services. A person sets them; once saved, nobody reads a value again, their agent included.

A secret is a key or credential a service sends with its requests, such as an API key. A person sets it, never an agent or a chat, and nobody reads it back once it is saved. How a service names one in code: Secrets in code.

Setting them

Does
crab secret request <service> On Cloud, answers a code and its page, https://crabtalk.ai/secrets/WDJB-MJHT, where an owner of the account, signed in, sets each unset required credential beside its provider's steps.
crab secret fill <service> Asks the person at this terminal for each credential and sets what they type: in the local host's secrets.toml, or on the account on Cloud. Refused when not run at a terminal.
printf %s "$VALUE" | crab secret put <service> <NAME> Provisions one declared secret from stdin for its manifest destinations. On Cloud, requires a signed-in session.
crab secret ls <service> Lists the names set, with their hosts. Values are never shown.
crab secret rm <service> <NAME> Revokes one. The service loses it at once.
  • A service's settings on crabtalk.ai show secret names and provisioning status. Credential values are entered through deployment or credential requests; destinations are read-only.
  • --copy callback=<url> gives request and fill the values the credentials have the person enter at the provider. request --credential <id> asks for one credential, set or not and optional or not, and --for says what it is for.
  • crab request <code> --wait returns once the person has set them, and crab request <code> --expire ends a code early; what was already saved stays set. Decline on the page turns the request down.
  • The deploy page asks for required secrets that are unset and saves them before deploying. crab deploy --copy app:callback=<url> supplies provider values by service and copy key.
  • A deploy with a required secret unset is refused (E0021); the running version stays unchanged. Saving secrets never starts a service stopped by its owner.

Rules

  • Only signed-in owners of the account provision, replace or revoke its services' secrets. API keys cannot do so.
  • A secret is sent only to its hosts, each named in full, such as api.example.com: no *, scheme, port or path, and at most 16. A secret with none is sent nowhere, whatever the service's code asks.
  • A credential's hosts in crab.toml declare its destinations. Changing them requires redeployment and fresh provisioning; an existing value never gains new destinations silently.
  • A value a credential gives a pattern for must match it.
  • Provisioning again replaces the stored value. Saved values are never returned, even for fields declared masked = false.
  • A name is up to 128 ASCII letters, digits and _, and does not start with a digit.
  • A value is 1 byte to 8 KiB on one line, with no control characters.
  • On Cloud, a new value reaches the service within 30 seconds, and values are stored encrypted with AES-256-GCM.
  • A call's logs, its record and its replay hold no secret.
  • The local host keeps its own secrets, apart from Cloud's, in secrets.toml under its root, readable by its owner alone.

Runtime secret resources

Runtime secrets are resources owned by the account. Each has a stable ID and explicit grants to services in that account. The service must declare secret_resources = true; each grant's hosts must fit its HTTP permissions.

On Cloud, ask an owner to provision a value and approve its service grant:

crab secret resource request app "Research Bot" --host api.example.com
crab request <code> --wait

The command prints the secret ID and a secure approval link. The owner enters the value on that page; the agent sees only its reference and provisioning status. Add --id <secret-id> to rotate an existing resource through this flow. Resource creation, rotation and grant changes do not redeploy the service.

At a person's terminal, crab secret resource create NAME and rotate ID read the value from stdin. resource ls lists metadata and grants; Cloud API keys need secrets:read. resource grant ID SERVICE --host HOST grants a service access; resource revoke ID SERVICE removes that grant. resource rm ID deletes the value and all grants. Cloud writes require a signed-in session; API keys cannot supply values or change grants directly. Local resources use the same commands against the local host.

Use the returned ID in application data and {secret:ID} in outgoing requests. The host holds the value and enforces the grant. Cloud pushes changes to running hosts; an unavailable host receives them when it synchronizes again. Deleting a service removes its grants and leaves account-owned resources intact.