Secrets and network access

A tool package gets nothing it does not declare. It reads only the secrets named in its caplo.yaml, and it reaches only the hosts listed there. Both lists are frozen into each published version.

Declare secrets

List each secret by name in caplo.yaml. Names are upper case: a letter, then letters, digits or underscores, up to 64 characters, and at most 50 per package.

secrets:
  - SHOP_API_KEY
  - SHOP_WEBHOOK_SECRET

Read a value from the call context:

const apiKey = secrets.get("SHOP_API_KEY");

secrets.get throws if the call has no value for the name. Secrets are never environment variables on Caplo, and caplo.yaml holds only names.

Provide the values

Each declared name gets its value in one of two ways:

A package value, set for this package only.
A workspace secret binding. A workspace secret is a value stored once and bound to any number of packages, for example one API key that three packages use. Rotating the workspace secret updates every package bound to it.

Binding a name to a workspace secret replaces the package’s own value. Live calls use a new or rotated value within a minute. A live call to a tool whose package declares a secret that has no value fails before the tool runs.

Values are write-only: once saved, neither the console nor the CLI shows them again.

Console
CLI

Package value or binding

Open Tools. Each tool package has a Secrets button; a package whose published version declares secrets without values shows a warning badge such as 1 secret not set.
Select Secrets. For each declared name, select Set value to store a value for This package only, or Use workspace secret to choose a workspace secret, then Save secret or Bind secret.
To remove one, select Unbind or Remove. Live calls that need it fail until it is set or bound again.

The list shows the names your latest published version declares. Setting a package value needs the Owner, Admin or Developer role; binding a workspace secret needs Owner or Admin.

Workspace secrets

Open Settings, then Secrets, and select Create secret. Names are lowercase letters, digits and hyphens, such as shop-prod. Rotate value replaces the value; Delete secret removes it and cannot be undone.

Run these in the package folder, or pass -p <package>. Values are read from a hidden prompt, or from standard input when it is not a terminal, so they never appear in your shell history.

# A value for this package only
caplo tool secret set SHOP_API_KEY

# Or: create a workspace secret once, then bind the package's name to it
caplo secret set shop-prod --description "Shop API production key"
caplo tool secret bind SHOP_API_KEY shop-prod

# Where each declared name gets its value
caplo tool secret list

In scripts, pipe the value in, for example from your CI secret store: printf '%s' "$SHOP_KEY" | caplo secret set shop-prod.

Command	What it does
`caplo tool secret set <NAME>`	Sets the package’s own value. Refused while the name is bound to a workspace secret.
`caplo tool secret unset <NAME>`	Removes the package’s own value.
`caplo tool secret bind <NAME> <workspace-secret>`	Fills the name from a workspace secret, replacing the package’s own value.
`caplo tool secret unbind <NAME>`	Removes the binding.
`caplo secret set <name>`	Creates a workspace secret or rotates its value.
`caplo secret list`	Lists workspace secrets and how many package secrets bind each.
`caplo secret usage <name>`	Lists the package secrets bound to a workspace secret.
`caplo secret delete <name>`	Deletes a workspace secret. Refused while any package secret is bound to it.

See the caplo tool secret and caplo secret references.

Secrets in development and tests

caplo tool dev reads each declared secret from an environment variable of the same name: SHOP_API_KEY=test-key caplo tool dev.
A fixture can carry test values in its secrets field. Use test credentials there, never production ones. See Test tools with fixtures.
Live calls never use these values; they use only what you set or bind in the workspace.

Allow network access

A package can make outbound requests only to the hosts in its egress list. Without the list, or with an empty one, it has no network access at all.

egress:
  - api.shop.example
  - "*.payments.example"

An entry is an exact host name, or *. followed by a domain to allow its subdomains. *.payments.example allows eu.payments.example but not payments.example itself; list both if you call both.
Host names only: no scheme, port or path. Up to 50 entries.
Even a listed host is refused if it resolves to a private, loopback, link-local or cloud metadata address. Tools cannot reach internal networks this way.

A request to any other host is refused before it leaves Caplo, and your code sees a failed request. The refusal is recorded with the invocation: caplo tool logs and remote fixture runs print it as egress denied <host>: <reason>.

Egress is enforced when the package runs on Caplo: in live calls and in caplo tool test --remote. A local caplo tool test uses your machine’s network, so run --remote before publishing to catch a missing host.