Secrets

Give a new Sandbox credentials without putting their values in source code, event data, or the Create request. Select existing workspace secrets by exact name; Inngest makes each value available as an environment variable with that name throughout the Sandbox. Secret selection is in the access-gated beta, and its API can change before launch.

Note Secret injection is not output redaction. Any code in the Sandbox can read selected values. A value printed to stdout, stderr, logs, or files can be returned by the Sandbox APIs.

Before you start

Create the secrets in the same Inngest workspace that will create the Sandbox. The public Sandbox REST API and JavaScript SDK select existing secrets; they do not create, list, rotate, or archive secret values.

Names are case-sensitive. Save a secret under the environment variable name the application expects, such as OPENAI_API_KEY.

Select secrets at Create

Direct client:

const sandbox = await inngest.sandboxes.create({
  name: `agent-${crypto.randomUUID()}`,
  vcpu: 1,
  memoryMb: 1024,
  environment: {
    APP_ENV: "beta",
  },
  secrets: ["OPENAI_API_KEY", "GITHUB_TOKEN"],
});

Middleware-backed client:

const sandbox = await step.sandbox.create("create-sandbox", {
  name: `agent-${event.data.jobId}`,
  vcpu: 1,
  memoryMb: 1024,
  secrets: ["OPENAI_API_KEY"],
});

REST:

{
  "name": "agent-job-42",
  "vcpu": 1,
  "memoryMb": 1024,
  "environment": {
    "APP_ENV": "beta"
  },
  "secrets": ["OPENAI_API_KEY", "GITHUB_TOKEN"]
}

The SDK and API send only the names. Values are injected under those same names and inherited by commands and managed processes.

Secret selection is supported only for a fresh Sandbox. A snapshot clone restores the environment captured by its snapshot and cannot select new secrets.

Environment precedence

Environment is layered in this order:

1. guest defaults;
2. literal Sandbox environment values and selected secret values; and
3. command- or process-specific environment values.

An operation-specific value can override a selected secret for that operation. A Create request cannot include the same key in both environment and secrets.

Selection, rotation, and lifecycle

Secret names resolve to stable secret identities when the Sandbox is created.

• Selection order does not affect Create identity.
• Rotating a secret changes the value fetched by a future launch, but does not replace a value already delivered to a running or paused guest.
• Archiving a selected secret and creating another secret with the same name affects new Sandboxes. An existing Sandbox remains bound to the original identity.
• Pause and Resume do not fetch secrets again.
• A user snapshot captures guest memory, disk, and environment after delivery. Values can remain in the snapshot and its clones.
• A clone does not fetch current values and cannot select additional secrets.

Rotation or archival cannot revoke a value already delivered to a guest or captured in a snapshot. Destroy Sandboxes and delete snapshots when their sensitive state is no longer needed.

Delivery and failure behavior

Names resolve inside the authenticated account and workspace. Secret values are envelope-encrypted at rest. Launch retrieval uses short-lived authorization bound to the workload and node; the node does not receive cloud credentials or encryption keys.

One authorized fetch attempt is permitted for the workload. A failed or lost fetch response is not replayed for that workload, and launch fails. Unknown, archived, duplicated, or colliding names reject Create as invalid input.

Validation and limits

• Each name is exact and case-sensitive.
• Each name must be non-empty and at most 256 UTF-8 bytes.
• Names cannot have leading or trailing Unicode whitespace.
• Names cannot contain =, carriage return, line feed, or NUL.
• Names must be unique and cannot overlap literal environment keys.
• Literal environment keys and selected names share a maximum of 256 entries.
• Resolved KEY=value data is limited to 64 KiB.

Security checklist

• Select only the credentials needed by code in that Sandbox.
• Never put secret values directly in literal environment fields.
• Do not print credentials or include them in returned command output.
• Treat files and snapshots created after injection as potentially sensitive.
• Destroy Sandboxes and delete snapshots when their sensitive state is no longer required.