Secrets

Secrets let an administrator store a credential once and make it available to chosen agents inside Stilla's sandboxed computer. The agent asks for a secret by name, Stilla injects the value as an environment variable, and the model never sees the value.

Without secrets, a credential an agent needs must be pasted into a chat message or into the agent's instructions. It then stays in that conversation permanently, is readable by anyone who can open it, and is sent to the model with every request. Storing it as a secret instead keeps the value out of the model's context, limits which agents may use it, and records every use.

Administrators manage secrets under Settings → Secrets, on the Team plan and above.

Read the leak section before adding production credentials

Stilla controls which agents may use which secret and keeps the value out of the model's context. It does not control what a command does with the value once it runs.

What a secret consists of

Field	Rules
Name	Uppercase letters, digits, and underscores, starting with a letter. Up to 100 characters.
Value	Up to 64,000 characters. Encrypted at rest. Never shown again after saving.
Description	Optional, up to 500 characters. Shown to the agent so it can pick the right one.

The name is the environment variable the agent references, so it cannot change without breaking existing commands. Names the sandbox already uses, such as PATH and GITHUB_TOKEN, are rejected. The value is write-only: no API returns it.

Granting access

Adding a secret does not grant access to it. A restriction policy must name the secret first.

Secrets behave differently from the rest of the restriction system. For every other system, a policy that does not mention it falls back to the policy's default access. Secrets have no such fallback. If a policy does not name a secret, agents under that policy cannot use it, and an agent running without a policy cannot use any secret.

You grant either the whole secrets system, which covers secrets added later, or one individual secret. The only levels are No access and Read, because an agent can use a value but can never create, change, or delete a secret. Both the agent's policy and the user's policy must allow the grant. Grants are keyed to the secret's identifier, so recreating a deleted secret under the same name does not carry the old grant over.

How an agent uses a secret

The agent calls organization_secrets_query for the names it is allowed to use, then names one in the secrets parameter of the shell tool. Values are never returned to the model. Injection lasts for one command. If any requested name is unknown or blocked, the whole call fails and nothing is injected.

Rotating and deleting

Rotating replaces the value in place, keeping the name, grants, and history. Deleting archives the secret and scrubs the value. Neither action affects a value that has already been used. If you suspect a value has been exposed, revoke it at the source first.

Audit log

Stilla records an audit event when a secret is created, rotated, or deleted, and each time one is injected into a command. No event stores the value.

An injection event identifies the secret by name and records the user, the chat and canvas it ran in, and the command that requested it. The command is masked when the log is read, because it is free-form text that may contain anything the agent typed. Events are written only for injections that actually happened: if any requested name is unknown or blocked, the command fails and nothing is recorded against the secret.

Each secret has its own usage log on its detail page, which is part of audit logging. Organizations without audit logging still see the usage count and last-used time in the settings table, and those track every injection.

Ways a secret can still leak

Most exposure is accidental

None of these require a malicious agent or an attacker. Assume that a granted secret can reach anywhere the agent's output reaches.

The value is an ordinary environment variable. Every process the command starts inherits it, including a script that dumps env or a dependency's install hook.
Command output returns to the model. Stilla does not scan or redact it. echo $MY_KEY, curl -v, set -x, or a tool that prints the credential in an error all put the value into the chat and the transcript.
Conversation content spreads. Once a value appears in a chat or canvas, it can be summarized, quoted into Slack, stored in agent memory, or read by anyone with access.
Network rules limit destinations, not payloads. The egress proxy controls which hosts a command may reach, not what it sends to an allowed host.
Prompt injection can misuse a granted secret. Policy decides which secrets an agent may use, not whether a particular use is sensible. See Prompt injection security.
Rotation does not retract copies. A value already in a transcript, a log, or a commit stays there.
Installed packages run with the same environment. Granting a secret to an agent that installs dependencies extends trust to whatever it installs.

Reducing the risk

Issue a narrow, dedicated credential at the source. Stilla decides who may use a credential; it cannot make a broad one safe.
Grant one secret at a time instead of allowing all of them.
Keep secrets away from agents that read external email, public issues, or arbitrary web pages.
Restrict the sandbox's allowed network destinations.
Monitor the audit log for use the workflow does not intend.