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.

List your secrets with the CLI:
nsc vault list

See the CLI docs for more.

Create Secret

Add new secrets to your vault.

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.

Create from File

For non-interactive creation, you can store the secret value in a file:
secret.txt
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

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.

Delete Secret

Delete a secret with --object_id:
nsc vault delete --object_id sec_abcde12345

See the CLI docs for more.

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

Define your Devbox configuration in a spec file, and include secret object IDs in env:

devbox.yaml
name: my-devbox
image: default
size: M
env:
  - name: GITHUB_TOKEN
    from_secret_id: sec_abcde12345

Then create a Devbox with --from:

devbox create --from devbox.yaml

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

Last updated