Vault — Runbook

Vault must be unsealed after every restart. Auto-unseal handles this automatically via Proxmox hook script — manual unseal is only needed if auto-unseal fails.

Secrets

Write a secret

Use the Vault Write Secret workflow in Forgejo Actions (workflow_dispatch):

Input	Description	Example
path	Path under secret/	gluetun/nordvpn
data	JSON key-value pairs	{"key": "value", "key2": "value2"}
patch	Merge keys instead of overwrite	true / false (default)

• Overwrite (default): replaces all keys at the path
• Patch: adds or updates specific keys, leaves others untouched

The workflow uses VAULT_TOKEN from Forgejo Actions secrets.

---

Claude Bot Token

Claude Code authenticates to Vault using a dedicated periodic token (policy: claude, 720h period, auto-renews).

Bootstrap / rotate the token

1. Run the Bootstrap Claude Vault Token workflow in Forgejo Actions (workflow_dispatch, no inputs)
2. The workflow creates the claude policy (if missing) and generates a new periodic token
3. The token is stored at secret/claude/vault-token and printed in the job logs
4. Update ~/.claude/settings.json on the workstation:

   {
     "env": {
       "VAULT_TOKEN": "<token from step 3>",
       "VAULT_ADDR": "http://192.168.1.106:8200"
     }
   }
   

5. Restart Claude Code for the new token to take effect

Verify token works

curl -s -H "X-Vault-Token: $VAULT_TOKEN" \
  "http://192.168.1.106:8200/v1/auth/token/lookup-self" | python3 -c \
  "import json,sys; d=json.load(sys.stdin)['data']; print(f'display_name={d[\"display_name\"]} policies={d[\"policies\"]} ttl={d[\"ttl\"]}s')"

---

Status

Check seal status

ssh [email protected] "VAULT_ADDR=http://127.0.0.1:8200 /usr/local/bin/vault status"

---

Restart

ssh [email protected] "pct exec 106 -- rc-service vault restart"

Remember: auto-unseal fires on LXC start via the Proxmox hook script. If restarting the service (not the LXC), unseal manually.

---

Unseal

Manual unseal (if auto-unseal fails)

ssh [email protected]
export VAULT_ADDR=http://127.0.0.1:8200
vault operator unseal   # run 3 times with 3 different unseal keys

Unseal keys are stored on chizuru at /etc/vault/unseal-keys.

---

Logs

Log	Contents	Location	Loki query	Format
Vault server	Auth events, seal/unseal, secret access, policy changes, errors	LXC 106 /var/log/vault.log	Not in Loki	Plain text
Auto-unseal hook	Unseal script output after LXC start	Proxmox host /var/log/vault-unseal.log	Not in Loki	Plain text

Notes: - Vault runs on Alpine LXC 106 and writes to a file, not systemd journal — it's the one remaining service without Loki forwarding - SSH access: ssh [email protected] "tail -f /var/log/vault.log" - Auto-unseal log: ssh [email protected] "cat /var/log/vault-unseal.log"

---

Troubleshooting

Vault sealed after LXC restart

Auto-unseal should have fired. Check the hook script ran:

ssh [email protected] "cat /var/log/vault-unseal.log"

If it failed, unseal manually (see above).

VAULT_TOKEN expired / permission denied in workflows

The VAULT_TOKEN Actions secret may have expired or been rotated. Generate a new token, update the Forgejo Actions secret, and re-run the failing workflow.

Cannot reach Vault at https://vault.eva-00.network

1. Check Caddy is running: ssh [email protected] "caddy status" (or via systemctl)
2. Check Vault LXC is up: ssh [email protected] "pct status 106"
3. Check Vault is unsealed: see Check seal status above