# Secrets

> Give a new Sandbox workspace credentials without putting their values in source code or event data.

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:

```typescript {{ title: "TypeScript" }}
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:

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

REST:

```json
{
  "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.