--- title: "Start a sandbox process with secrets" method: POST path: "/api/sandbox/{id}/processes" tags: ["Sandboxes"] --- # Start a sandbox process with secrets `POST /api/sandbox/{id}/processes` ## Request - Base URL: `https://api.hyperbrowser.ai` - URL: `https://api.hyperbrowser.ai/api/sandbox/{id}/processes` - Auth: API key in header `x-api-key` - TypeScript: (a function with typed inputs; its response is checked against the schema) Starts a process in a running sandbox with secrets as environment variables for that process only. Pass `secrets`, a `vault`, `onePassword` fields, or any of them together: the vault's variables come first and `secrets` is merged over them, while a 1Password variable can't also come from another source. Values are decrypted on the sandbox's host and never returned; a `totp` secret sets the code current when the process starts, and `onePassword` fields are read from 1Password at that moment. Not supported on GPU sandboxes. Secrets are enabled for teams on request; please contact support to enable them (otherwise 403 SECRETS_FEATURE_DISABLED). Restricted API keys need both the sandboxes.read and secrets.use scopes. Don't retry blindly after a 502 SECRET_PROCESS_OUTCOME_UNKNOWN: the process may have started, so check the sandbox's process list first. ## Path parameters - `id` string, uuid, required ## Request body - StartSandboxSecretProcessParams: Provide at least one of `secrets`, `vault` and `onePassword`. - `command` string, required: Shell command to run. - `cwd` string: Working directory. - `env` object: Plain environment variables. A variable that `vault`, `secrets` or `onePassword` sets can't also be in `env` (400 SECRET_SOURCES_INVALID). - `timeoutMs` integer: Process timeout in milliseconds. - `runAs` string: User to run the process as. - `vault` union - string: A vault's name. - object: A vault with customer-protected entries: its name, and the envelopes you unwrapped from GET /api/vaults/{id}/wrapped. Its other entries are delivered as usual. - `name` string, required - `unwrapped` object, required: Environment variable to unwrapped envelope, one per customer-protected entry. If an entry now resolves to another secret or version, the request fails with 409 SECRET_VAULT_CHANGED: fetch and unwrap the vault again. - `secrets` SecretReferences: Environment variables to set from secrets, keyed by variable name (letters, digits and `_`, not starting with a digit), at most 32. `{}` is the same as none. An `op_token` secret returns 409 SECRET_TYPE_MISMATCH, an unknown secret 404 SECRET_NOT_FOUND, and a missing version 404 SECRET_VERSION_NOT_FOUND. - `onePassword` OnePasswordSource: Environment variables read from fields of one 1Password vault when the process starts, signed in with a 1Password service account token stored as an `op_token` secret. Nothing is stored: the sandbox's host resolves the references, and values are never returned. A variable set here can't also be set by `vault`, `secrets` or `env` (400 SECRET_SOURCES_INVALID). Browser sessions fill 1Password fields through POST /api/session/{id}/credentials/fill instead. - `token` union, required: The `op_token` secret, by name, holding the service account token. A name uses its latest version. An unknown name returns 404 SECRET_NOT_FOUND, a secret of another type 409 SECRET_TYPE_MISMATCH, and a token without a value 404 SECRET_VERSION_NOT_FOUND. A customer-protected token is passed as `{name, version, unwrapped}`, as for `secrets`. - string - SecretReference - `name` string, required: Name of a secret of type `secret` or `totp`. A `totp` variable holds the code current when the process starts. A customer-protected secret also needs `unwrapped` (otherwise 400 SECRET_REQUIRES_CUSTOMER_UNWRAP). - `version` union: A version number, or `latest`. Omit for the latest version. - 'latest' - integer - `unwrapped` string: Customer-protected secrets only, and required for them: the inner envelope you unwrapped from GET /api/secrets/{id}/versions/{version}/wrapped. `version` must then be that version's number, not `latest`. See [Customer-protected secrets](/sandboxes/customer-keys). - `vault` string, required: The 1Password vault's name or ID. 1-256 characters: a 1Password name or ID without `/` or `?`, control or format characters, and not `.` or `..`. - `fields` object, required: Environment variable name (letters, digits and `_`, not starting with a digit) to the field it takes. 1 to 32 fields. ## Response `200` Success - StartSandboxSecretProcessResponse - `process` SandboxSecretProcess, required: The started process. Its environment is never returned. - `id` string, required: Process ID. Use it with the sandbox process APIs to read output or wait for the process. - `status` 'queued' | 'running' | 'exited' | 'failed' | 'killed' | 'timed_out', required - `command` string, required - `cwd` string, required - `pid` integer - `exit_code` integer - `started_at` integer, required: Unix time in milliseconds. - `completed_at` integer: Unix time in milliseconds. - `secrets` SandboxSecretBinding[], required: Each variable the process received, with its source. Never values. - `env` string, required: Environment variable name. - `name` string: Secret name. - `secretId` string, uuid - `version` integer: The version delivered, with `latest` resolved. - `secretType` 'totp': Present for `totp` secrets, whose variable holds the code current at process start. - `reference` string: The `op://` reference the value was read from, for a 1Password variable. - `tokenSecret` string: Name of the `op_token` secret used to sign in to 1Password, for a 1Password variable. - `source` SecretSource, required: Where a variable came from: the request's `vault`, its `secrets`, or its `onePassword`. - `type` 'vault' | 'secrets' | 'onePassword', required - `name` string: The vault's name, with `type: vault`. - `overrides` SecretSource[]: Earlier sources that set the same variable and were replaced, oldest first. Present only when there were any. Never `onePassword`: a 1Password variable can't be set by another source. - `type` 'vault' | 'secrets' | 'onePassword', required - `name` string: The vault's name, with `type: vault`. ## Other responses - `400`: Invalid request body, the sandbox is a GPU sandbox, or SECRET_SOURCES_INVALID (`env` sets a variable the vault or `secrets` also sets, a 1Password variable is also set by another source, the vault has no entries, or they set more than 32 variables). SECRET_REQUIRES_CUSTOMER_UNWRAP: a customer-protected secret, vault entry or 1Password token was passed without its unwrapped envelope, or with `latest` instead of a version number. SECRET_PROTECTION_MISMATCH: `unwrapped` was passed for a secret that isn't customer-protected. - `401`: Authentication required. - `403`: API_KEY_SCOPE_DENIED or SECRETS_FEATURE_DISABLED. - `404`: Sandbox not found, SECRET_NOT_FOUND, SECRET_VERSION_NOT_FOUND (also when the `onePassword` token has no value), or VAULT_NOT_FOUND. - `409`: The sandbox is stopped or its runtime isn't ready, or SECRET_TYPE_MISMATCH (an `op_token` secret in `secrets` or the vault, or a `onePassword` token that isn't an `op_token`). SECRET_DIGEST_MISMATCH: an unwrapped envelope isn't the one stored for that version. SECRET_VAULT_CHANGED: a vault entry changed since the vault was unwrapped; unwrap it again. SECRET_KEY_RETIRED: the version was encrypted to a retired platform key; add a new version. - `422`: The sandbox couldn't use a value. SECRET_VALUE_INVALID: a stored value can't be used, such as an invalid TOTP seed; upload a new version. SECRET_ONEPASSWORD_REFERENCE_FAILED: 1Password couldn't resolve a field (`details.envs` and `details.reasons` name the variables). SECRET_ONEPASSWORD_AUTH_FAILED: 1Password rejected the token, or the token is malformed or its sign-in address isn't on 1password.com, 1password.ca, 1password.eu or their subdomains, so it wasn't sent. Other codes, such as SECRET_ENVELOPE_INVALID, mean a stored envelope couldn't be opened; `details` names the variable, secret and version. - `429`: SECRET_ONEPASSWORD_RATE_LIMITED: 1Password is rate limiting the service account (retryable). - `500`: Internal server error. - `501`: The sandbox's runner doesn't support secrets. SECRET_TOTP_UNSUPPORTED: the sandbox's host can't deliver TOTP secrets yet, and nothing started (not retryable on this route; a new sandbox may run on an upgraded host). - `502`: SECRET_PROCESS_OUTCOME_UNKNOWN: the start wasn't confirmed and the process may be running. Not retryable. SECRET_ONEPASSWORD_FAILED: 1Password couldn't be reached and nothing started (retryable). - `503`: SECRET_PROCESS_NOT_STARTED: the sandbox's host couldn't be reached and no process was started (retryable). SECRET_ONEPASSWORD_FAILED (retryable). SECRETS_NOT_CONFIGURED or SECRET_KEY_UNAVAILABLE: the sandbox's host can't decrypt secrets. - `504`: SECRET_PROCESS_TIMEOUT: timed out before the process was started (retryable). ## Changes - **2026-11-10** `94dc06948680`: 3 breaking, 4 info - added `#/components/schemas/VaultSource` to the `vault` request property `allOf` list - the `onePassword/allOf[#/components/schemas/OnePasswordSource]/token` request property type changed from `string` to no type - the `vault` request property type changed from `string` to no type - added the new optional request property `secrets/allOf[#/components/schemas/SecretReferences]/additionalProperties/unwrapped` - …3 more - **2026-10-15** `225d94fe61a0`: 2 warning, 1 info - added the new `onePassword` enum value to the `secrets/items/overrides/items/type` response property for the response status `200` - added the new `onePassword` enum value to the `secrets/items/source/type` response property for the response status `200` - added the new optional request property `onePassword` - **2026-10-15** `6ca0b00ee564`: 1 info - endpoint added [Operation history](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/changes/api/sandbox/:id/processes/post.md) --- [API](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api.md) - [All operations](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hyperbrowser/apis/hyperbrowser-api/revisions/ef089024c533?raw)