The primary secrets engine stores all Lobstack credentials as versioned key-value pairs. KV v2 provides version history, soft delete, and check-and-set for safe concurrent updates.
Vault uses the Kubernetes auth method — pods authenticate using their ServiceAccount JWT tokens. No static tokens or passwords are needed. Each service role gets a scoped Vault token with limited TTL.
Auth Roles
# Lobstack API — can read all platform secrets + manage agent secrets
vault write auth/kubernetes/role/lobstack-api \
bound_service_account_names=lobstack-api \
bound_service_account_namespaces=lobstack-control-plane \
policies=lobstack-api \
ttl=1h \
max_ttl=4h
# Agent pods — can ONLY read their own agent secret
vault write auth/kubernetes/role/lobstack-agent \
bound_service_account_names=lobstack-agent \
bound_service_account_namespaces=lobstack-agents \
policies=lobstack-agent \
ttl=1h \
max_ttl=4h
Vault policies define exactly what each service can access. The agent policy uses templated paths — each agent can only read secrets for its own agent ID, enforced cryptographically by Vault.
vault-policies.hcl — Agent Policy
# Agent Policy (templated — each agent reads ONLY its own secrets)
path "secret/data/lobstack/agent/{{identity.entity.metadata.agent_id}}" {
capabilities = ["read"]
}
# Agents can encrypt/decrypt their workspace data
path "transit/encrypt/agent-data" {
capabilities = ["update"]
}
path "transit/decrypt/agent-data" {
capabilities = ["update"]
}
Secrets are delivered to pods via two mechanisms, used together for defense-in-depth:
💉
Vault Agent Injector
A sidecar container is injected into each pod. It authenticates to Vault, fetches secrets, and writes them as environment variable files. Secrets are refreshed every 5 minutes.
📁
Secrets Store CSI Driver
Mounts Vault secrets as files in the pod's filesystem. Syncs to Kubernetes Secrets for envFrom usage. Supports automatic rotation.
The src/lib/vault.ts module provides a TypeScript client that handles authentication, secret retrieval, encryption, and caching with automatic environment variable fallback.
Using the Vault Client
import { getApiKeys, setAgentSecret, deleteAgentSecret, encrypt, decrypt } from "@/lib/vault";
// Get all platform API keys (cached, falls back to env vars)
const keys = await getApiKeys();
keys.anthropicApiKey; // From Vault or ANTHROPIC_API_KEY env
// Store agent-specific secrets
await setAgentSecret("agent-abc123", {
ai_api_key: "sk-ant-...",
telegram_token: "123456:ABC-...",
});
// Clean up on agent teardown
await deleteAgentSecret("agent-abc123");
// Encrypt/decrypt via Transit engine
const cipher = await encrypt("sensitive-data"); // vault:v1:...
const plain = await decrypt(cipher); // sensitive-data
Every Vault operation is logged — secret reads, writes, encryptions, decryptions, authentication events, and policy changes. Audit logs are written to persistent storage and retained for 2+ years, aligned with SOC 2 requirements.
✅
Initialization
Run infra/kubernetes/vault/vault-init.sh after deploying Vault to configure engines, policies, and Kubernetes auth. See Compliance Readiness for the full audit trail requirements.