Quick Start

Quick Start

This walks through a minimal end-to-end setup: initializing a repo, adding an encrypted secret, editing it, rendering it to a file, and running a health check.

Before you start

You need:

• keyseal installed and on your PATH
• sops installed and on your PATH
• An age key pair (generate one with age-keygen if you don't have one)

---

1. Initialize the repository

Run this from the root of the Git repository where you want to store secrets:

keyseal init

This creates:

• keyseal.yaml - Keyseal configuration
• .sops.yaml - SOPS creation rules (with placeholder recipients)

And scaffolds directories:

production/platform/
production/infra/
production/tenants/
staging/platform/
staging/infra/
staging/tenants/

The generated .sops.yaml contains placeholder age recipients (age1REPLACE_ME). You must replace these with real age public keys before SOPS will encrypt anything.

# generate a key if you need one
age-keygen -o ~/.config/sops/age/keys.txt
# the public key is printed to stdout, e.g.:
# Public key: age1abc123...

Edit .sops.yaml and replace the placeholder values:

creation_rules:
  - path_regex: production/.*\.enc\.yaml$
    age: age1abc123...,age1recovery456...
  - path_regex: staging/.*\.enc\.yaml$
    age: age1abc123...,age1recovery456...

---

2. Add a secret

keyseal add production/platform/app

This creates a starter document, encrypts it via SOPS, and writes only the ciphertext to production/platform/app.enc.yaml.

To use a built-in template:

keyseal add production/platform/app --template laravel

Available templates: laravel, stripe, mail, mysql-app. See Templates.

---

3. Edit the secret

keyseal edit production/platform/app

This opens production/platform/app.enc.yaml in SOPS's interactive editor (your $EDITOR or SOPS default). You edit the decrypted view, save, and SOPS re-encrypts in place.

---

4. Render to a file

keyseal render production/platform/app --out /run/secrets/app.env

This decrypts the file, validates its contents, and writes a dotenv-formatted file. The output file is written atomically (temp file + rename) with mode 0600 by default.

To render to stdout instead:

keyseal render production/platform/app --stdout

To render multiple secrets merged together:

keyseal render production/platform/app production/platform/mail --out /run/secrets/app.env

When multiple secrets are merged, later files win on key conflicts.

---

5. Run a command with secrets injected

keyseal exec production/platform/app -- php artisan migrate

Secrets are injected as environment variables into the subprocess. They override any matching keys in the current environment. The subprocess inherits all other environment variables.

---

6. Run doctor

keyseal doctor

Doctor checks your configuration, SOPS setup, and all discovered .enc.yaml files. Common things it catches:

• Placeholder recipients still in .sops.yaml
• Plaintext files at .enc.yaml paths (file was never actually encrypted)
• SOPS binary missing or not executable
• keyseal.yaml invalid or missing

Fix whatever it reports before committing secrets. See Doctor for the full breakdown.

---

Typical development loop

# first time in a new repo
keyseal init
# edit .sops.yaml to add real age public keys
keyseal add production/platform/app --template laravel
keyseal edit production/platform/app
keyseal doctor

# every time you need to use secrets locally
keyseal exec production/platform/app -- your-command
# or
keyseal render production/platform/app --out /run/secrets/app.env