Secrets

Never store sensitive values like API keys, passwords, or tokens as plaintext in workflow files or configuration. Namespace Secrets provide a secure way to store and manage sensitive information across your workloads.

Encryption at Rest

All secrets stored in Namespace are encrypted at rest using industry-standard encryption algorithms. Your sensitive data is never stored in plaintext on our systems.

Comprehensive Audit Logging

Every secret access — whether revealed, created, updated, or deleted — emits a detailed, immutable audit log. This provides complete visibility into how and when your secrets are being used, supporting compliance and security monitoring requirements.

Managing Secrets

You can manage secrets using the CLI, the VaultService API, or the Namespace Dashboard.

Secrets are versioned — each update creates a new version. You can use optimistic concurrency control to prevent concurrent modifications by passing the current version when updating or deleting a secret.

Secrets can optionally be marked as revealable at creation time. Only revealable secrets can have their value retrieved later via the API or CLI. This setting is immutable after creation.

Labels can be attached to secrets at creation time for organization and filtering. Labels are immutable and shared across all versions of a secret.

List Secrets

View all your secrets and configuration values in your vault.

Namespace CLI

List your secrets with the CLI:

nsc vault list

See the CLI docs for more.

Dashboard

Open your workspace Vault to see your secrets.

Create Secret

Add new secrets to your vault.

Namespace CLI

Create a secret with the CLI, and provide the secret value when prompted:

nsc vault add --description "key description"

See the CLI docs for more.

Dashboard

Open Vault and press "New Secret" to create a secret.

Guide: how to create a secret

Create from File

For non-interactive creation, you can store the secret value in a file:

here-goes-my-key

Then provide it with the --from_file flag:

nsc vault add --from_file secret.txt --description "secret from file"

Update Secret

Namespace CLI

Update a secret with --object_id; you'll be prompted for the new value:

nsc vault set --object_id sec_abcde12345

For non-interactive update, provide the value with a file:

nsc vault set --object_id sec_abcde12345 --from_file key.txt

See the CLI docs for more.

Dashboard

Find the secret in your Vault, expand the menu next to it and choose Edit.

Guide: how to update a secret

Delete Secret

Namespace CLI

Delete a secret with --object_id:

nsc vault delete --object_id sec_abcde12345

See the CLI docs for more.

Dashboard

Find the secret in your Vault, expand the menu next to it and choose Delete.

Guide: how to delete a secret

Using Secrets

Secrets can be provided as environment variables. They are resolved at creation time and injected into the container's environment.

No secrets are injected by default — they must be explicitly requested.

In Instances

Use the env_vars field in ContainerRequest with from_secret_id set to the secret's object ID:

{
  "env_vars": [
    { "name": "DATABASE_URL", "from_secret_id": "secret-object-id" }
  ]
}

In Devboxes

Reference secrets from a Blueprint. Open a Blueprint from the Blueprints page, and under Environment, press + Add secret. Enter the environment variable name, pick the secret from your vault, and save the Blueprint.

Then create a Devbox from the Blueprint:

CLI

devbox create --blueprint my-blueprint

TS SDK

const devbox = await client.devboxes.create({
  name: "my-devbox",
  blueprint: "my-blueprint",
});

Dashboard

On the Blueprints page, open the ... menu next to the Blueprint, select Create Devbox, give it a name, and press Create Devbox.

After the Devbox is created, the secret value is available through the configured environment variable name.