---
url: https://ws.kloudkit.com/settings/secrets.md
description: >-
  Manage sensitive credentials in Kloud Workspace with the ws-cli secrets
  command — encrypt passwords, API keys, and SSH keys instead of storing
  plaintext.
---

# Secrets

![Secrets](/icons/secrets.svg){.doc-image}

Kloud Workspace applications often require sensitive credentials: database passwords, API
keys, SSH keys, and authentication tokens.
Storing these in plaintext or version control is insecure.

The `ws-cli secrets` command provides a means of managing secrets using
**strong Argon2 encryption**, ensuring safe retrieval in your development environment.

## Master Keys

A master key is required to encrypt and decrypt secrets.

### Generate a Master Key

```sh
# Standard master key
ws secrets generate master --output .master.key --mode 0o600

# Longer 64-byte key
ws secrets generate master --length 64 --output .master.key

# Output to stdout (CI/CD)
ws secrets generate master --raw
```

The `--mode` flag sets file permissions *(e.g., `0o600` for owner-only access)*.

### Master Key Lookup

The master key will be retrieved from the following locations *(in order)*:

1. `--master` flag.
2. `WS_SECRETS_MASTER_KEY` environment variable.
3. `WS_SECRETS_MASTER_KEY_FILE` environment variable.
4. Default path: `/etc/workspace/master.key`

```sh
export WS_SECRETS_MASTER_KEY_FILE=./master.key
ws secrets encrypt "my-secret"
```

## Encryption & Decryption

### Basic Usage

```sh
# Encrypt
ws secrets encrypt "my-secret" --master .master.key

# Decrypt
ws secrets decrypt "encrypted-value" --master .master.key

# Encrypt/Decrypt to files
ws secrets encrypt "my-secret" --output encrypted.txt --master .master.key
ws secrets decrypt "..." --output secret.txt --mode 0o600 --master .master.key
```

Supports `stdin` input and *multiline encrypted values* for better readability:

```sh
echo "my-secret" | ws secrets encrypt - --master .master.key
cat encrypted.txt | ws secrets decrypt - --master .master.key
```

## Seed

For declarative secret projection — inline `${secrets.NAME}` values and whole-file `secret: true`
entries in the seed manifest — see the [seed documentation](/settings/seed).

## Authentication Passwords

Generate *Argon2id* password hashes for workspace login:

```sh
PASSWORD=$(echo -n "password" | ws secrets generate login --raw)
```

Use in Docker deployments:

```sh
docker run \
  -e WS_AUTH_PASSWORD_HASHED=$PASSWORD \
  ghcr.io/kloudkit/workspace:v0.4.0
```

See [authentication documentation](/editor/authentication) for details.

## Quick Reference

### Common Flags

* **`--master <key>`:** Master key or file path.
* **`--output <file>`:** Write to file.
* **`--mode <perm>`:** File permissions *(octal or decimal)*.
* **`--raw`:** Disable styling.
* **`--force`:** Overwrite existing files.

See [ws secrets command reference](/tools/ws-cli#secrets-ws-secrets) for complete syntax.