Secrets

A secret is a per-project credential — an API key, token, or connection string — that a session needs but that must not live in the repository. Machine stores secrets on the project, never on the account, and encrypts every value with AES-256-GCM using a key derived per project.

Identifier and name

Each secret has two names. The identifier is the handle you use in the CLI and in an agent's secrets grant. The name is the uppercase environment-variable key injected into the sandbox, for example STRIPE_API_KEY. In most projects the identifier and the name match. They differ only when a project holds several candidate values for one name — for example, a primary and a backup Google Maps key can both resolve to GOOGLE_MAPS_API_KEY.

Every access rule uses the identifier. None of them uses the name.

Shared and personal scope

A secret is either shared or a personal override:

• Shared — the project-wide value. Every project member with read access sees every shared secret. Machine has no per-member sharing control for a single secret.
• Personal override — your own value for one name, used instead of the shared row for sessions you start. Today Machine uses this only for one OAuth login credential.

Machine never lets an LLM provider key, for example ANTHROPIC_API_KEY, become a personal override. The model gateway always reads the shared row.

Which agents receive a secret depends on its delivery mode:

• A Sandbox secret reaches every agent in the project. The agent's secrets list does not narrow it. Only a session's own secrets allowlist can hold it back. The platform's own coordinator agent receives none.
• A Network boundary or Machine service (HTTPS broker) secret reaches only an agent whose secrets list in kortix.yaml names its identifier. Omitting secrets means none. See Agents.

Delivery

Delivery decides where the value is allowed to go. Every secret has one delivery mode. The default is Sandbox.

Sandbox is the only mode that puts plaintext in the sandbox. Agent code can read, print, and forward it. Every other mode keeps the value outside.

Change the mode in the project's Secrets page, or from the CLI:

machine secrets delivery STRIPE_API_KEY denied

Add a secret

machine secrets set STRIPE_API_KEY=sk_live_...

Grant a secret to an agent

A grant matters only for Network boundary and Machine service delivery. A session receives such a secret only when the agent it runs names the identifier in its secrets list. Matching uses the identifier, not the name, and ignores case.

A Sandbox secret ignores the agent's secrets list. Since October 2026 it reaches every agent in the project, whether or not the agent lists it.

From the dashboard

The Secrets page marks a Network boundary or Machine service secret that no agent can receive: No agent can receive this secret. Choose an agent there and confirm. Machine edits kortix.yaml and commits it as chore(agents): grant <IDENTIFIER> to <agent>.

The grant works whether or not the manifest already declares that agent. An agent the manifest does not declare gets a new entry holding this one secrets list. An agent that is already declared keeps every other field — model, tools, connectors — and the identifier joins its existing list. An agent that already admits the identifier needs no commit, and Machine makes none.

An agent on secrets: all is a special case. all cannot carry a session-scoped secret, so Machine writes an explicit list: every identifier the project has today, plus this one. Nothing the agent receives today changes. A secret you add later needs its own grant.

Two cases refuse the grant:

• A project on kortix_version: 1 (kortix.toml) has no agents map to edit. The request fails with 400 and manifest_v1_unsupported. Edit the manifest by hand, or move the project to kortix_version: 2.
• A secret whose delivery is Disabled has nothing to deliver. The request fails with 409 and secret_not_grantable. Choose a delivery mode first.

If the project has no agents: block yet, read The first agents: block changes the whole project before you confirm.

By hand

The same grant, written directly:

kortix_version: 2
agents:
  my-agent:
    secrets: [STRIPE_API_KEY]

The first agents: block changes the whole project

The dashboard asks you to confirm the first time it adds an agents: block, because the block also becomes the project's launch roster and governs each agent's other grants. See the manifest reference.

List your secrets

Run machine secrets ls to see which secrets a project declares and which ones have a value set. An agent runs the same command as kortix secrets ls inside its sandbox.

The list is configuration metadata. It never returns secret values. A scoped agent token sees every Sandbox secret, plus the other identifiers in its agent grant. A session-specific secrets_allowlist controls delivery into that session, but it does not hide configuration metadata that the agent grant permits.

Rotate a secret

machine secrets set STRIPE_API_KEY=sk_live_new...

Remove a secret

Run machine secrets unset STRIPE_API_KEY (or unset <identifier>), or delete it from the project's Secrets page.

Share a value without seeing it

Run machine secrets request STRIPE_API_KEY to create a link. Anyone with the link can enter the value. You never see it. Links stay valid for 7 days by default; adjust with --expires <minutes> (max 30 days). An expired link shows a clear "expired" page — mint a fresh one with the same command.

Network boundary

Network boundary is the strictest delivery mode. Machine registers the value with the Platinum sandbox provider. Platinum adds the value to matching outbound requests at its own egress edge, after the request has left the sandbox.

The sandbox never receives the value. It is not an environment variable, it is not a file, and no alias or placeholder stands in for it. Grepping the sandbox environment for the identifier returns nothing. The agent writes an ordinary request with no credential in it, and the header appears in flight.

Set it up

kortix_version: 2
agents:
  my-agent:
    secrets: [STRIPE_API_KEY]

From the CLI, the same configuration is one command:

machine secrets delivery STRIPE_API_KEY egress \
  --allow-host api.stripe.com \
  --inject-header authorization \
  --template 'Bearer {{secret}}'

Hosts match exactly

List every host you call, one exact hostname per line. There is no pattern matching, and the boundary accepts nothing narrower than a host.

api.example.com does not cover uploads.api.example.com. Add the second host to the same secret, or use a second secret. Machine rejects an unenforceable policy with 400 when you save it — it never stores a rule it cannot apply.

Use Machine service delivery with the HTTPS broker consumer when you need wildcards, paths, or method filters. Machine makes that request itself, so it can enforce controls Platinum cannot.

One header per host

A host and a header can be claimed by one secret only. Saving a second secret that targets the same pair fails with 409 and secret_boundary_destination_conflict, naming the secret that already holds it.

Two secrets on the same host with different headers are fine. Platinum injects both.

HTTPS only

Platinum has to terminate TLS to rewrite a header, so a policy host must be called over HTTPS. Plain HTTP is refused before the request leaves:

egress to "api.stripe.com" is blocked: this sandbox's policy puts a secret in a
request header for this host, and that requires HTTPS

That message is a policy refusal, not a network fault.

Verify it with two probes

Run both probes from inside the sandbox, against a host that is in the policy. The example below uses postman-echo.com, which serves one endpoint of each kind. Add it as an allowed host for the duration of the test.

# 1. Reachability — an endpoint that does NOT echo request headers.
curl -s -o /dev/null -w '%{http_code}\n' https://postman-echo.com/status/200
# expected: 200

# 2. Injection — an endpoint that DOES echo request headers.
curl -sS https://postman-echo.com/get
# expected: curl: (52) Empty reply from server

Read the pair together. Probe 1 first — it is the only one that tells you the host is reachable.

Also confirm the value never reached the guest:

env | grep -c STRIPE_API_KEY
# expected: 0

A policy host presents Platinum's per-sandbox certificate, which the sandbox already trusts:

curl -sv https://postman-echo.com/status/200 2>&1 | grep 'issuer:'
# issuer: O=Platinum; CN=Platinum egress proxy (sandbox sbx_...)

A host that is not in the policy passes through untouched and presents its own origin certificate.

End-to-end example

kortix.yaml:

kortix_version: 2
default_agent: my-agent
agents:
  my-agent:
    secrets: [STRIPE_API_KEY]

Secret configuration:

machine secrets set STRIPE_API_KEY=sk_live_...
machine secrets delivery STRIPE_API_KEY egress \
  --allow-host api.stripe.com \
  --inject-header authorization \
  --template 'Bearer {{secret}}'

The agent then calls Stripe with no credential of its own:

curl -s -o /dev/null -w '%{http_code}\n' https://api.stripe.com/v1/customers
# expected: 200

The same request from a session on another provider, or from an agent whose secrets list omits STRIPE_API_KEY, returns 401. Nothing else changes.

CLI commands

Run machine secrets --help for every delivery flag. Inside a session sandbox, agents run the same commands as kortix secrets ….

Names and permissions

Format rules for the two names:

Reading or writing a secret needs the project.secret.read or project.secret.write permission. A custom project role can withhold either permission, even from a manager.

REST routes

All routes sit under /v1/projects/{projectId}.

POST /secrets rejects names that start with KORTIX_. It returns 409 if the identifier already exists with a different name. It rejects the exact name CODEX_AUTH_JSON with 400 — Machine manages that secret through ChatGPT subscription onboarding.

Both write routes return a delivery_sync object when the change had to reach running sandboxes. ok: false means the value is saved but at least one live session still uses the previous one; the listed sessions pick it up on restart.

A secret in the list carries delivery_blocked_reason. The value no_agent_grant means no agent can receive this Network boundary or Machine service secret. null means it is granted, the mode needs no grant (Sandbox and Disabled), or Machine could not read the manifest.

POST /secrets/{identifier}/grant clears that reason. It returns already_granted: true when the agent's list already admits the identifier, in which case Machine commits nothing. It returns adopted_governance: true when the edit added the project's first agents: block — the change described above. It answers 400 manifest_v1_unsupported for a kortix.toml project and 409 secret_not_grantable for a disabled secret.

Rotation and propagation

A secret write does not wait for a session restart. Machine pushes the change to every active sandbox in the project:

1. Machine builds a new environment snapshot. Sandbox secrets go to every agent, narrowed only by the session's secrets allowlist.
2. The sandbox writes the snapshot to the live agent environment. New tool calls pick up the change right away.
3. If the changed secret is an LLM provider credential, Machine restarts OpenCode.

This push is best-effort. The API call that changes the secret returns before the push finishes. A failed push is only logged, not retried. A sandbox with a failed push keeps the old value until the next successful push, or until the session restarts.

Rotating a network-boundary secret updates the Platinum replica in place. The sandbox does not restart, because it never held the value.

Model credentials

A project on Machine's managed model access needs no key of its own. To bring your own, set the provider variables your OpenCode provider config references.

Do not use a generic provider verification result as runtime proof. It cannot prove the selected model, region, entitlement, and API dialect. Send a real prompt through the exact model.