> ## Documentation Index
> Fetch the complete documentation index at: https://namespace.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Secrets

export const GuideFlow = ({id, title, frameSize = "wide"}) => {
  const paddingBottom = frameSize === "small" ? "calc(56.23387790197765% + 10px)" : frameSize === "medium" ? "calc(56.23387790197765% + 47px)" : "calc(62.004487658937926% + 47px)";
  return <div style={{
    position: "relative",
    paddingBottom,
    height: 0
  }}>
			<iframe id={id} title={title || "Step-by-step guide"} src={`https://app.guideflow.com/embed/${id}`} width="100%" height="100%" style={{
    overflow: "hidden",
    position: "absolute",
    border: "none"
  }} allow="clipboard-read; clipboard-write" allowFullScreen />
		</div>;
};

export const CenteredImage = ({src, alt, width, caption, className}) => {
  const [basePath, setBasePath] = useState("");
  useEffect(() => {
    const path = window.location.pathname;
    setBasePath(path === "/docs" || path.startsWith("/docs/") ? "/docs" : "");
  }, []);
  return <Frame caption={caption} className={className} style={{
    maxWidth: width,
    marginInline: "auto"
  }}>
			<OptimizedImage src={`${basePath}${src}`} alt={alt} />
		</Frame>;
};

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](/docs/workspaces/security#audit-logs). 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](/docs/reference/cli/vault-add), the [VaultService API](https://buf.build/namespace/cloud/docs/main:namespace.cloud.vault.v1beta), or the [Namespace Dashboard](https://cloud.namespace.so/workspace/vars).

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.

<Tabs>
  <Tab title="Namespace CLI">
    List your secrets with the CLI:

    ```bash theme={null}
    nsc vault list
    ```

    See the [CLI docs](/docs/reference/cli/vault-list) for more.
  </Tab>

  <Tab title="Dashcboard">
    Open your workspace [Vault](https://cloud.namespace.so/workspace/vars) to see your secrets.

    <CenteredImage width={800} alt="Vault secrets" src="/docs/images/architecture/vault-secrets.png" />
  </Tab>
</Tabs>

### Create Secret

Add new secrets to your vault.

<Tabs>
  <Tab title="Namespace CLI">
    Create a secret with the CLI, and provide the secret value when prompted:

    ```bash theme={null}
    nsc vault add --description "key description"
    ```

    See the [CLI docs](/docs/reference/cli/vault-add) for more.
  </Tab>

  <Tab title="Dashboard">
    Open [Vault](https://cloud.namespace.so/workspace/vars) and press "New Secret" to create a secret.

    <GuideFlow id="1pz32xxbvk" title="Guide: how to create a secret" frameSize="small" />
  </Tab>
</Tabs>

#### Create from File

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

```text secret.txt theme={null}
here-goes-my-key
```

Then provide it with the `--from_file` flag:

```bash theme={null}
nsc vault add --from_file secret.txt --description "secret from file"
```

### Update Secret

<Tabs>
  <Tab title="Namespace CLI">
    Update a secret with `--object_id`; you'll be prompted for the new value:

    ```bash theme={null}
    nsc vault set --object_id sec_abcde12345
    ```

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

    ```bash theme={null}
    nsc vault set --object_id sec_abcde12345 --from_file key.txt
    ```

    See the [CLI docs](/docs/reference/cli/vault-set) for more.
  </Tab>

  <Tab title="Dashboard">
    Find the secret in your [Vault](https://cloud.namespace.so/workspace/vars), expand the menu next to it and choose Edit.

    <GuideFlow id="np1e27dbek" title="Guide: how to update a secret" frameSize="small" />
  </Tab>
</Tabs>

### Delete Secret

<Tabs>
  <Tab title="Namespace CLI">
    Delete a secret with `--object_id`:

    ```bash theme={null}
    nsc vault delete --object_id sec_abcde12345
    ```

    See the [CLI docs](/docs/reference/cli/vault-delete) for more.
  </Tab>

  <Tab title="Dashboard">
    Find the secret in your [Vault](https://cloud.namespace.so/workspace/vars), expand the menu next to it and choose Delete.

    <GuideFlow id="yr44qxytlr" title="Guide: how to delete a secret" frameSize="small" />
  </Tab>
</Tabs>

## 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:

```json theme={null}
{
  "env_vars": [
    { "name": "DATABASE_URL", "from_secret_id": "secret-object-id" }
  ]
}
```

### In Devboxes

Define your Devbox configuration in a [spec file](/docs/devbox/managing#creating-from-a-spec-file), and include secret object IDs in `env`:

```yaml devbox.yaml theme={null}
name: my-devbox
image: default
size: M
env:
  - name: GITHUB_TOKEN
    from_secret_id: sec_abcde12345
```

Then create a Devbox with `--from`:

```bash theme={null}
devbox create --from devbox.yaml
```

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