vaultkit

Agentic-first secrets vault service. Store, retrieve, and manage encrypted secrets (API keys, passwords, tokens) with TTL and audit logging. Plain text API, agent-driven, single Go binary with JSON file storage.

Quick Start

# Build
make build

# Run (starts on :7474)
./vaultkit

# Auth flow
curl -X POST http://localhost:7474/auth/request -d '{"email":"you@example.com"}'
# → ok: OTP sent | workspace=ws_abc12 | hint: check stderr for the code in dev mode

curl -X POST http://localhost:7474/auth/verify -d '{"email":"you@example.com","code":"123456"}'
# → token=vt_... workspace=ws_abc12

# Create a secret
curl -X POST http://localhost:7474/secrets \
  -H "Authorization: Bearer vt_..." \
  -d '{"name":"stripe_key","value":"sk_live_abc123","tags":["payments"],"ttl":"24h"}'
# → handle=secret_abc12 name=stripe_key tags=payments ttl=24h

# Retrieve a secret (decrypts value)
curl http://localhost:7474/secrets/secret_abc12 -H "Authorization: Bearer vt_..."
# → handle=secret_abc12 name=stripe_key value=sk_live_abc123 tags=payments ttl=24h accessed=1

# List all secrets
curl http://localhost:7474/secrets -H "Authorization: Bearer vt_..."
# → handle=secret_abc12 name=stripe_key tags=payments ttl=24h

# Delete a secret
curl -X DELETE http://localhost:7474/secrets/secret_abc12 -H "Authorization: Bearer vt_..."
# → ok: secret_abc12 deleted

API Reference

Method	Path	Description
GET	/help	Operating manual for agents
POST	/auth/request	Request OTP (body: {"email":"..."})
POST	/auth/verify	Verify OTP → bearer token (body: {"email":"...","code":"..."})
POST	/secrets	Create a secret
GET	/secrets	List all secrets (values not shown)
GET	/secrets/{handle}	Retrieve a secret (decrypts value)
PATCH	/secrets/{handle}	Update a secret
DELETE	/secrets/{handle}	Delete a secret
GET	/workspace	Get workspace info
GET	/audit?limit=20	List recent audit entries
POST	/mcp	MCP JSON-RPC endpoint

Response Format

• Plain text by default — one labeled, grepable line per record
• JSON — via Accept: application/json header or ?format=json query param
• Errors — error: message | hint: what to do next

Encryption

Secrets are encrypted at rest with AES-256-GCM. The encryption key is auto-generated on first run and logged to stderr. To use a fixed key, set VAULTKIT_ENC_KEY to a 64-character hex string (32 bytes).

TTL

Set TTL on create or update: 30m, 24h, 7d. Expired secrets are hidden from list/get and cleaned up periodically.

Configuration

Flag	Env	Default	Description
-addr	VAULTKIT_ADDR	:7474	Listen address
-db	VAULTKIT_DB	vaultkit.json	Database file path
-secret	VAULTKIT_SECRET	auto-generated	Token signing secret
-enc-key	VAULTKIT_ENC_KEY	auto-generated	Encryption key (64-char hex)
-smtp-host	VAULTKIT_SMTP_HOST	empty	SMTP host for OTP emails
-smtp-port	VAULTKIT_SMTP_PORT	empty	SMTP port
-smtp-user	VAULTKIT_SMTP_USER	empty	SMTP username
-smtp-pass	VAULTKIT_SMTP_PASS	empty	SMTP password

Build

make build    # CGO_ENABLED=0, single static binary
make test     # go test -race
make vet      # go vet

License

MIT