Variables and secrets
Variables are plaintext configuration passed to your agents. Secrets are envelope-encrypted values that never enter an agent's context.
Variables and secrets
Helios stores two kinds of key-value data. They look similar and behave very differently.
| Variable | Secret | |
|---|---|---|
| Stored as | Plaintext | Envelope-encrypted |
| Readable back | Yes | No — write-only |
| Passed to agents | Yes, as run context | No |
Variables
A variable is non-sensitive configuration: an environment name, a channel to post to, a repository slug, a threshold. Every workflow run receives the variables visible to its project as context the agent may use.
Because they arrive as context rather than as text substitution, you refer to them by name in the prompt and let the agent do the rest:
Post the digest to the Slack channel named in the DIGEST_CHANNEL variable.
Skip the run entirely if ENVIRONMENT is not "production".Variables are stored in plaintext, are readable by anyone who can read the resource they're scoped to, and are passed into the agent's context. Never put a credential in a variable.
Secrets
A secret is a sensitive value. Helios encrypts it with envelope encryption: a unique data key is generated per secret from AWS KMS, used to encrypt the value with AES-256-GCM, and then itself stored encrypted under a KMS master key. The plaintext data key is discarded immediately. Decryption requires a KMS call bound to that specific record.
Secrets are write-only. Once saved, the API never returns the plaintext — not to the UI, and not to an agent.
Secrets are not injected into agent prompts. Agents authenticate to your tools through integrations, where Helios applies credentials server-side and injects short-lived tokens at the network layer — so the agent acts on your behalf without ever holding a credential. See sandboxes.
The same envelope encryption protects your integration credentials, database connection strings and SSH keys, and MCP server credentials.
Scoping and precedence
Variables and secrets are each set at one of four levels:
- Workflow (most specific)
- User
- Project
- Organization (most general)
When the same key exists at several levels, the most specific level wins. Set
DIGEST_CHANNEL at the organization level for a sane default, then override it on the one workflow
that should post somewhere else.
A key must be unique within a level, but the same key may appear at different levels — that is the point.
Managing them
Variables and secrets live under the project or organization they're scoped to. Creating and editing
them requires the editor role on that resource; listing them requires user. See
roles and permissions.
Rotating a secret is a plain edit: save the new value, then revoke the old one at the provider. Runs already in flight continue with the value they started with.
Last updated on
Roles and permissions
Helios has two layers of access control: an organization role that every member carries, and per-resource roles that grant access to specific projects, workflows, chats, and integrations.
SSO and SCIM
Federate identity into Helios with SAML 2.0 or OIDC, provision and deprovision users automatically with SCIM 2.0.