A small, single-user token store for AI agents. You keep API tokens and passwords in one place. Agents can list them and use them, but they must give a reason each time, and every use is logged. Tokens you mark as sensitive need your approval (passkey or password) before each use window.
- tokd is the server: Go, SQLite, values encrypted with AES-256-GCM, web app for you.
- tok is the client: one static binary for macOS, Linux and Windows.
- skills/tok/SKILL.md teaches Claude Code (or any agent that reads skills) how to use it.
- Web app: add and edit tokens (name, scope, what it is, when to use, env var, expiry, "needs approval"). The list shows values masked (
abcd••••••••wxyz, fully hidden under 10 characters), with show and copy buttons. Manage scopes, audit events, see logins and revoke them, manage passkeys. - Scopes such as
home,work,acme. Each token has one scope. Each machine's login is limited to the scopes you tick when approving it. tok login <server>: a device flow. The CLI prints a link and a code. You approve in the browser with a passkey or password, pick the scopes, and pick the lifetime (default and maximum set on the server).tok ls: the catalog the agent sees. It shows name, scope, description, when to use, added, last used, approval flag and expiry. It never shows values.tok exec --reason ... NAME -- cmd: runscmdwith the token in an environment variable and masks the value in its output.tok update: installs the latest tok release from GitHub (checksum-verified) and refreshes the Claude Code skill unless it is a symlink. Plaintokandtok statusshow the server's tokd version and say when a newer tok or tokd release exists (checked at most once a day).tok get --reason ... NAME: prints the value. When tok runs under an AI agent (AI_AGENT,CLAUDECODE,CLAUDE_CODE_SESSION_IDorCODEX_THREAD_IDset; not whenAI_AGENTends in_harness, i.e. the harness itself runs tok, as for a Claude Code MCPheadersHelper) it refuses unless--revealis given, so agents useexecand the value stays out of their context. A reveal by an agent always needs your approval (passkey or password), for every reveal and for any token, even ones not marked "needs approval"; tok opens the approval page itself.tok exec --no-redactunder an agent is treated the same way.- Approval: a gated token makes tok print an approval link and exit 3. You open the link, check the reason, host, directory and command, and confirm with a passkey or password. You then choose 5, 15 or 60 minutes. Within that window the same machine can use the token again without asking.
- Event log: every use, denial, approval, login and change, with the reason, host, login, directory, command and agent session (Claude Code session id, T3 thread id).
Images: ghcr.io/paidem/tokd (linux/amd64 + arm64). :latest and :X.Y.Z come from release tags vX.Y.Z, :main from the main branch. Release tags also publish the tok binaries on the GitHub release page.
Local, single machine:
docker compose up -d --build
open http://localhost:19191 # set the password, then add a passkey in Settings
tok login http://localhost:19191Passkeys work on http://localhost because browsers treat localhost as a secure context. Any other host needs HTTPS.
On a server, put it behind HTTPS and set TOKD_URL to the exact origin you open in the browser. Passkeys are bound to that host name, so changing it later means registering them again. Some options:
- Tailscale, own node (recommended):
deploy/tailscale/runs a Tailscale sidecar so tokd ishttps://tok.<tailnet>.ts.net, independent of the host. The name, passkeys and logins survive moving to another host (copydata/,key/,ts-state/). See the comments in itscompose.yaml. - Tailscale on the host:
tailscale serve --bg --https=8443 http://127.0.0.1:19191, thenTOKD_URL=https://<host>.<tailnet>.ts.net:8443. - Any reverse proxy with a certificate, reachable only from your own network or VPN. Don't expose it to the internet.
| env | default | |
|---|---|---|
TOKD_URL |
http://localhost:19191 |
public origin; used for passkeys, CSRF checks and links |
TOKD_ADDR |
:19191 |
listen address |
TOKD_DATA |
./data (/data in the image) |
SQLite database |
TOKD_DOWNLOADS |
./dist (/downloads in the image) |
client binaries and SKILL.md served at /dl/ |
TOKD_KEY_FILE |
$TOKD_DATA/master.key |
32-byte key, created on first start; compose keeps it in a separate volume |
TZ |
UTC |
time zone for the web UI |
Back up both the database and the key. Neither is any use without the other.
From a running tokd (the Docker image bundles tok for macOS, Linux and Windows plus the agent skill):
curl -fsSL https://tok.example.ts.net/install.sh | sh # tok -> ~/.local/bin; skills for detected Claude Code and Codex
tok login https://tok.example.ts.netThe installer adds the Claude Code skill at ~/.claude/skills/tok when ~/.claude exists, and the Codex skill at ~/.agents/skills/tok when codex is on PATH or ${CODEX_HOME:-$HOME/.codex} exists. Both are installed when both agents are found. The /install page lists individual downloads. Override the binary location with TOK_BIN_DIR; setting TOK_SKILL_DIR installs only to that skill directory instead of detecting agents. Symlinked skill directories and SKILL.md files are left untouched. Downloads use temporary files beside their destinations and rename them after success, preserving existing files if a download fails.
From source: make dist builds every platform into dist/ (what tokd serves at /dl/ when run outside Docker), or go build -o ~/.local/bin/tok ./cmd/tok.
The config is stored in ~/.config/tok/config.json (%AppData%\tok\config.json on Windows), mode 0600. Override the path with TOK_CONFIG.
- Single user. The password is bcrypt-hashed and only a fallback. Passkeys are preferred. Failed attempts slow down exponentially after 5 tries in 15 minutes.
- A machine login is a bearer token, stored hashed on the server. Anything running as you on that machine can use your tokens within the login's scopes until it expires or you revoke it. That is the design. The controls are: a short login lifetime, scopes, the mandatory reason, the audit log and per-token approval.
- An approval needs a fresh passkey or password check. An agent on the same machine can't approve its own request.
- Web sessions, pending approvals and approval windows live in memory. A server restart clears them, and you approve again.
- Values are encrypted at rest. The key file sits next to the database unless you move it (
TOKD_KEY_FILE), so encryption only protects backups or copies of the database made without the key. - Output masking in
tok execis a convenience. A command can still leak a value in a transformed form (base64, a file it writes, and so on).