ellulDocs

Sandboxes

Secrets and Environment

Storing API keys and credentials safely so the agent can use them only with explicit approval.

Application secrets (Stripe keys, OpenAI keys, database URLs to external services) live in the per-sandbox secrets manager. The agent never sees them by default. Reading or injecting a secret requires an env permission gate that you approve at the moment of use.

Where secrets live

Each sandbox has its own secret store, accessible at Settings > Secrets. Secrets are:

  • Encrypted at rest on your encrypted storage volume.
  • Scoped to one sandbox; not visible to other sandboxes.
  • Never sent to the ellul control plane.
  • Never visible in logs.

Adding a secret

1

Open Settings > Secrets in the sandbox

The list shows current secrets by name. Values are masked.

2

Click 'Add secret'

Enter a name (STRIPE_SECRET_KEY, DATABASE_URL, etc.) and the value.

3

Save

The secret is stored encrypted. You can update or delete it at any time.

The action is recorded in the audit log without the value.

How the agent uses a secret

The agent never reads secrets directly. Instead, it asks for the env permission gate when it needs to run a command that requires one.

The flow:

  1. The agent decides it needs STRIPE_SECRET_KEY for the next command.
  2. It requests env with the secret name and a one-line reason.
  3. A popup appears showing what is being requested and why.
  4. You approve or deny.
  5. On approval, the platform issues a one-time, short-lived token. The agent runs exactly one command with the secret injected. The gate closes immediately.

The env gate's TTL is short (around 30 seconds, single-use) precisely because secret injection is high-risk.

Secret classification

The platform classifies secrets by name pattern when you add them:

  • High-risk patterns (*_SECRET_*, *_KEY, *_TOKEN, *_PASSWORD) are highlighted.
  • Database URLs are recognised and may show connection metadata for confirmation.
  • Generic names get neutral treatment.

You can override the classification or mark a secret as sensitive manually.

Bulk import

For migrating from another platform, you can paste a .env-style block in Settings > Secrets > Bulk Import. Each line is parsed as KEY=value. The platform shows a preview before saving so you can confirm.

Rotation

When a secret needs to be rotated (an API key compromised, a partner asks for a new value):

  1. Update the secret value in Settings > Secrets.
  2. Restart any running services that read the secret at startup.
  3. The audit log records the change.

The platform does not automatically restart application processes; that is your decision based on the application's behaviour.

Exposure acknowledgements

If a secret is read while a non-redacted log gate (logs) is active, the platform marks an exposure event. You can review and acknowledge exposures in Settings > Secrets > Exposures. Acknowledging records that you reviewed the exposure; it does not affect the secret itself.

We recommend acknowledging promptly so the audit trail is clean.

What about the per-sandbox database

The per-sandbox database is provisioned for you. Its connection string is available to your application without explicit secret management; it is wired in at sandbox creation. You only manage external service credentials in Secrets.

Where to go next