Secrets & vault
Your credentials live in a single age-encrypted file on your VPS. They are decrypted at service start and exposed only to the Han AI processes that need them.
The vault
| Item | Value |
|---|---|
| Path | ~/.hanai-vault.age (under the hanai user’s home) |
| Format | age-encrypted key/value file |
| Created by | The provisioner during step 8 of setup |
| Read by | systemd at boot, rendered into /etc/hanai/runtime.env and /etc/hanai/dashboard.env |
What’s in it
| Key | What it is |
|---|---|
TELEGRAM_BOT_TOKEN | The bot token from BotFather. |
OPENAI_API_KEY | Language model and transcription provider key. |
AIRTABLE_PAT | Personal access token scoped to your base. |
AIRTABLE_BASE_ID | The Airtable base ID for your workspace. |
SESSION_SECRET | Auto-generated. Signs dashboard session cookies. |
URL_TOKEN_SECRET | Auto-generated. Signs short-lived URLs. |
SMTP_* | Optional. Host, user, password, from-address for the email capability. |
CHROMA_URL | Optional override for the local vector store. |
How loading works
- At boot, systemd reads
/etc/hanai/runtime.envand/etc/hanai/dashboard.env. - These files are rendered from the age vault during provisioning and on update.
- The runtime wraps secret access so that a missing value returns
nullrather than crashing — capabilities degrade gracefully when a credential isn’t set.
What this means for you
- If a capability needs a credential you haven’t provided, the AI COO knows it’s unavailable and won’t pretend it can use it.
- You can add or rotate a credential later. Your operator drops it into the vault and restarts the service.
- Nothing reads the vault except your VPS.
Rotating a credential
Message your operator with what needs rotating. Rotation is a vault edit plus a service restart. The bot is back online in under a minute.
Next
- The systemd services — which services read which secrets.
- Where your data lives — the other half of your VPS state.