> ## Documentation Index > Fetch the complete documentation index at: https://hyperbrowser.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Start a sandbox process with secrets > Run a command in a sandbox with secrets or a vault as environment variables for that process only. See the [secrets guide](/docs/sandboxes/secrets) for SDK and CLI examples. ## OpenAPI ````yaml openapi.json POST /api/sandbox/{id}/processes openapi: 3.0.1 info: title: Hyperbrowser API version: 1.0.0 servers: - url: https://api.hyperbrowser.ai description: Production server security: [] paths: /api/sandbox/{id}/processes: post: tags: - Sandboxes summary: Start a sandbox process with secrets description: >- Starts a process in a running sandbox with secrets as environment variables for that process only. Pass `secrets`, a `vault`, or both: the vault's variables come first and `secrets` is merged over them. Values are decrypted on the sandbox's host and never returned; a `totp` secret sets the code current when the process starts, and a 1Password vault reads its fields 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. operationId: startSandboxSecretProcess parameters: - name: id in: path required: true schema: type: string format: uuid description: Sandbox ID. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StartSandboxSecretProcessParams' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/StartSandboxSecretProcessResponse' '400': description: >- Invalid request body, the sandbox is a GPU sandbox, or SECRET_SOURCES_INVALID (`env` sets a variable the vault or `secrets` also sets, the vault has no entries, or they set more than 32 variables). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '403': description: API_KEY_SCOPE_DENIED or SECRETS_FEATURE_DISABLED. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '404': description: >- Sandbox not found, SECRET_NOT_FOUND, SECRET_VERSION_NOT_FOUND, or VAULT_NOT_FOUND. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '409': description: >- The sandbox is stopped or its runtime isn't ready, or SECRET_TYPE_MISMATCH (an `op_token` secret was named). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '422': description: >- 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 an entry (`details` names the variables). SECRET_ONEPASSWORD_AUTH_FAILED: 1Password rejected the token. Other codes, such as SECRET_ENVELOPE_INVALID, mean a stored envelope couldn't be opened; `details` names the variable, secret and version. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '429': description: >- SECRET_ONEPASSWORD_RATE_LIMITED: 1Password is rate limiting the service account (retryable). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '500': description: Internal server error. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '501': description: >- The sandbox's runner doesn't support secrets. SECRET_TOTP_UNSUPPORTED or SECRET_ONEPASSWORD_UNSUPPORTED: the sandbox's host can't deliver TOTP secrets or read 1Password vaults yet, and nothing started (not retryable on this route; a new sandbox may run on an upgraded host). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '502': description: >- 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). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '503': description: >- 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. content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' '504': description: >- SECRET_PROCESS_TIMEOUT: timed out before the process was started (retryable). content: application/json: schema: $ref: '#/components/schemas/SecretErrorResponse' security: - ApiKeyAuth: [] components: schemas: StartSandboxSecretProcessParams: type: object properties: command: type: string minLength: 1 maxLength: 8192 description: Shell command to run. cwd: type: string maxLength: 4096 description: Working directory. env: type: object additionalProperties: type: string maxLength: 32768 description: >- Plain environment variables. A variable that `vault` or `secrets` sets can't also be in `env` (400 SECRET_SOURCES_INVALID). timeoutMs: type: integer minimum: 0 maximum: 86400000 description: Process timeout in milliseconds. runAs: type: string maxLength: 128 description: User to run the process as. vault: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$ description: >- Name of a vault whose variables to set. Applied before `secrets`. Together they set at most 32 variables. A vault without entries returns 400 SECRET_SOURCES_INVALID, and an unknown one 404 VAULT_NOT_FOUND. secrets: allOf: - $ref: '#/components/schemas/SecretReferences' description: >- Secrets to set as environment variables for this process only, merged over the vault's variables, so `secrets` wins on a clash. They aren't added to the sandbox's default environment. required: - command additionalProperties: false description: Provide `secrets`, `vault`, or both. StartSandboxSecretProcessResponse: type: object properties: process: $ref: '#/components/schemas/SandboxSecretProcess' secrets: type: array items: $ref: '#/components/schemas/SandboxSecretBinding' description: Each variable the process received, with its source. Never values. required: - process - secrets SecretErrorResponse: type: object properties: code: type: string description: Machine-readable error code, such as SECRET_NOT_FOUND. message: type: string error: type: string description: >- Set instead of `code` by authentication and API key scope errors (API_KEY_SCOPE_DENIED). requiredScopes: type: array items: type: string description: The scope the API key is missing, with API_KEY_SCOPE_DENIED. retryable: type: boolean description: >- Whether repeating the same request can succeed. Set on delivery errors. details: type: object additionalProperties: true description: >- Extra information for some codes, such as `origin` for CREDENTIAL_ORIGIN_NOT_ALLOWED or `pages` for CREDENTIAL_PAGE_AMBIGUOUS. description: >- HTTP failure. Secret errors include `code` and `message`; request validation errors include only `message`; API key scope errors include `error`, `message` and `requiredScopes`. SecretReferences: type: object maxProperties: 32 additionalProperties: $ref: '#/components/schemas/SecretReference' description: >- 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. example: OPENAI_API_KEY: name: openai-key SandboxSecretProcess: type: object description: The started process. Its environment is never returned. properties: id: type: string description: >- Process ID. Use it with the sandbox process APIs to read output or wait for the process. status: type: string enum: - queued - running - exited - failed - killed - timed_out command: type: string cwd: type: string pid: type: integer exit_code: type: integer started_at: type: integer format: int64 description: Unix time in milliseconds. completed_at: type: integer format: int64 description: Unix time in milliseconds. required: - id - status - command - cwd - started_at SandboxSecretBinding: type: object description: >- One environment variable a process received, never its value. A stored secret has `name`, `secretId` and `version`; a variable from a 1Password vault has `reference` and `tokenSecret` instead. properties: env: type: string description: Environment variable name. name: type: string description: Secret name. secretId: type: string format: uuid version: type: integer description: The version delivered, with `latest` resolved. secretType: type: string enum: - totp description: >- Present for `totp` secrets, whose variable holds the code current at process start. reference: type: string description: The `op://` reference a 1Password vault entry was read from. tokenSecret: type: string description: Name of the `op_token` secret the 1Password vault signed in with. source: $ref: '#/components/schemas/SecretSource' overrides: type: array items: $ref: '#/components/schemas/SecretSource' description: >- Earlier sources that set the same variable and were replaced, oldest first. Present only when there were any. required: - env - source SecretReference: type: object properties: name: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9_-]{0,127}$ description: >- Name of a secret of type `secret` or `totp`. A `totp` variable holds the code current when the process starts. version: oneOf: - type: string enum: - latest - type: integer minimum: 1 maximum: 2147483647 description: A version number, or `latest`. Omit for the latest version. required: - name additionalProperties: false SecretSource: type: object description: 'Where a variable came from: the request''s `vault`, or its `secrets`.' properties: type: type: string enum: - vault - secrets name: type: string description: 'The vault''s name, with `type: vault`.' required: - type securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.