Secrets

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

# 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

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

Encryption & Decryption

Basic Usage

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

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

Vault

For declarative bulk secret injection using YAML vault files, see the Vault documentation.

Authentication Passwords

Generate Argon2id password hashes for workspace login:

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

Use in Docker deployments:

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

See authentication documentation 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 for complete syntax.