ASM – Agent Secrets Manager
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
ASM – Agent Secrets Manager
Website: https://eltomato89.github.io/asm/ · Deutsch: README.de.md
A self-hosted, multi-user secrets manager built for AI agents such as Claude Code. Agents find secrets via MCP, request them with a project and a reason, and you approve each request in the browser. By default the value never reaches the agent, only the process it starts.
Server (
apps/server): Fastify API, OAuth 2.1 for MCP clients, MCP endpoint/mcp, serves the web UI. SQLite.Web UI (
apps/web): approve requests, manage secrets, vaults, devices, audit log. Available in English and German; it follows the browser language and can be switched under Settings → Language.CLI (
apps/cli, commandasm): hands approved secrets to commands or.envfiles.
Security model
Hybrid delivery. The agent requests a secret via MCP (
request_secret, defaultdelivery: "cli"). Once approved, it only receives a grant ID and callsasm run --grant <id> -- <command>: the CLI fetches the value and sets it as an environment variable for that process only. The value therefore never ends up in the conversation history or at the model provider. Grants are valid for 15 minutes and, by default, for a single use. If the requesting device belongs to a linked group (a Claude Code device with its attached CLIs, see Devices), only that group's CLI can redeem the grant; any other CLI getswrong_device_group. A grant stays bound to the group it was issued for, even if the group changes before it is redeemed. Grants of unlinked devices can be redeemed by any of your CLIs, as before.Plaintext is opt-in per secret.
delivery: "plaintext"only works if "Allow plaintext to agents" is enabled on the secret (default: off). A plaintext value then appears in the transcript, in logs and at the model provider – use it only for non-critical values. Agents can never change this setting.Approvals. Every request (read or change) waits for your decision (
A/Din the UI) and expires after 5 minutes. Auto mode approves automatically for a limited time (default 30 min, at mostASM_AUTO_MODE_MAX_MIN) and for selected vaults – every auto-approval is recorded in the audit log.Standing approval per device. Trust a single device for days instead of minutes (Devices → "Standing approval…"): until a date you pick (at most
ASM_STANDING_APPROVAL_MAX_DAYS, default 90), for all secrets, for selected vaults (including secrets added to them later) or for a selected list of secrets, optionally including the secrets the device creates itself in its default vault (secrets it creates in other vaults still need approval). Reads are covered; changes only if you also allow them. After the expiry, ASM either asks every time again, or asks once and extends the standing approval by a preset number of days when you approve. Every automatic approval is recorded as "via standing approval"; revoking the device removes it. A CLI attached to a Claude Code device has no standing approval of its own: its requests are covered by the main device's standing approval (and extend it on renewal).Agents may propose a standing approval. A Claude Code device that keeps asking for the same secrets can propose one itself (MCP
request_standing_approval). It shows up as a separate card "… wants standing access" above the requests (and as a push notification). The proposal is limited: selected vaults or a list of secrets only (never all secrets), reads only, at mostASM_STANDING_REQUEST_MAX_DAYSdays. An agent can only propose while its device has no active standing approval, with at most one open proposal per device, at most 3 proposals per device in 24 hours, and not within 24 hours of a denial; a proposal expires after 30 minutes. You can only narrow it before approving (deselect vaults or secrets, shorten the duration, switch renewal to "ask again"); anything wider you set afterwards in the regular dialog. Approving always needs a recent sign-in (or a passkey on the push page), "Deny" needs nothing, and a proposal is never approved automatically – not by auto mode, not by a standing approval. The audit log records it as "proposed by agent, adjusted by you" with what you changed.whoamitells the agent whether it may propose right now (standing_request).What agents may do. Create secrets (immediately), change them (only with approval), archive them (immediately, with a reason). Never delete, never restore.
Archive instead of delete. Archived secrets no longer show up in searches and can be neither read nor changed; pending requests for them are denied. A human can restore them.
Versions. Every change creates a new version with actor, project and reason. Old values remain viewable and can be restored.
Audit log with a hash chain: each entry contains the hash of the previous one, so tampering is detectable (see limitations below).
Devices. Every pairing (Claude Code, CLI) is a separate device that you approve in the browser and can revoke at any time. Refresh tokens rotate; reuse locks the device. Each device has a default vault where it creates secrets when it doesn't name one (initially your personal vault; changeable in the device list, which needs a recent sign-in). If you lose access to that vault, it falls back to your personal vault.
Linked devices. A CLI can be attached to a Claude Code device (the main device) – during
asm loginon the browser confirmation page ("Link to an existing device"), or later in the device list ("Link…"). Linking is opt-in: nothing is preselected, and if the main device has an active standing approval, the page warns that the CLI will be approved automatically under it – only link a CLI you just started yourself. The attached CLI then uses the main device's standing approval and default vault; its own are dropped when you link it. "Unlink" makes it a standalone device again with empty settings; unlinking or moving a CLI to another main device cancels its open grants and requests. Revoking the main device also revokes its attached CLIs by default; uncheck the option to detach them instead.Deactivating accounts. Admins can deactivate accounts in Settings (offboarding): the person is signed out, can no longer sign in, and all their devices are revoked.
Encryption. AES-256-GCM, with a separate key per secret that is encrypted with the master key. Sensitive actions (reveal a value, pair a device, auto mode, setting a standing approval or a device's default vault, approving a standing approval proposed by an agent, linking or unlinking a device) require a sign-in no older than 10 minutes. Sign in with password or passkey.
Related MCP server: vault-mcp
Setup (Docker)
The image is based on node:24-alpine. Without Docker, the server needs Node.js ≥ 24 (LTS) and pnpm 11.
docker build -t asm .
# Generate the master key – back it up separately from the data! Without it, all secrets are lost.
# Separate directory (secrets/ is excluded in .gitignore and .dockerignore).
mkdir -p secrets && chmod 700 secrets
docker run --rm asm node apps/server/dist/scripts/generate-key.js > secrets/asm_master_key
chmod 600 secrets/asm_master_key
sudo chown 1000:1000 secrets/asm_master_key # the container runs as user node (UID 1000) and must be able to read the fileNever commit the key or bake it into the image. Ideally keep it entirely outside the repo (then adjust the path
under secrets.asm_master_key.file in the Compose file).
Then copy docker-compose.example.yml, adjust ASM_PUBLIC_URL and start:
docker compose -f docker-compose.example.yml up -d
docker compose -f docker-compose.example.yml logs asm | grep "ASM setup token"Open ASM_PUBLIC_URL in the browser, enter the setup token from the log and create the first account (admin).
Add more users under "Settings". You can also add a passkey there.
Variable | Meaning | Default |
| Public address (origin), required. Determines the passkey domain, OAuth issuer and origin check. | – |
| Master key (base64, 32 bytes) as a file or inline. If missing, the server exits with an error. | – |
| Behind a reverse proxy: number of proxy hops (usually |
|
| Maximum duration of auto mode. |
|
| Maximum duration of a standing approval per device, in days (at most |
|
| Maximum duration an agent may propose for a standing approval, in days. |
|
| Data directory ( |
|
| HTTP port. |
|
| Directory containing the CLI bundle ( | Image: |
| Comma-separated IPv4/IPv6 CIDRs (e.g. | empty = no restriction |
| Contact for Web Push services ( |
|
Reverse proxy
TLS terminates at the proxy; ASM itself only speaks HTTP. Examples for Traefik and Caddy are included, commented out, in
docker-compose.example.yml.ASM_PUBLIC_URLmust be exactly the https origin under which browsers and agents reach ASM (e.g.https://asm.example.com, without a path). http is only allowed forlocalhost.Set
ASM_TRUST_PROXY=1(one proxy hop; with several proxies, their count or the proxy IPs/CIDRs). Otherwise ASM only sees the proxy's IP, and the per-IP rate limits hit all users together. Then make the container port reachable only by the proxy.Passkeys need https and a domain name – an IP address does not work.
Do not buffer live requests (server-sent events) and MCP long polls (up to ~50 s); keep timeouts ≥ 60 s.
Push approval from your iPhone
When a request is waiting for approval, ASM sends a push notification to your devices. Tapping it opens a small approval page: "Approve" (with Face ID) or "Deny". This works on the go even though ASM is not publicly reachable – only the approval page is exposed.
Setup (once, on your home network/VPN):
Open ASM in Safari (
ASM_PUBLIC_URL), sign in, Share → "Add to Home Screen" (iOS ≥ 16.4).Launch ASM from the new icon, Settings → "Notifications" → "Enable", and allow.
"Send test" checks delivery. To approve, your account needs a passkey (Face ID).
ASM generates the VAPID keys itself on first start (private key stored in the DB, encrypted with the master key).
Public paths: /approve/, /api/approve/, /assets/, /favicon.svg, /theme-init.js, /sw.js,
/manifest.webmanifest, /icons/icon-180.png, /icons/icon-192.png, /icons/icon-512.png. Everything else only from
the home network/VPN. Use one hostname for inside and outside so that the same passkey works.
Nginx Proxy Manager – option A (UI):
Access Lists → new list "Home network": under Access
allow 192.168.0.0/16(and the VPN network if any), restdeny, no users, "Satisfy Any".Proxy Host
asm.example.de→http://asm:8080, SSL enabled, Access List = "Home network".Custom Locations without an access list, same target (
asm,8080):/approve/,/api/approve/,/assets/,/favicon.svg,/theme-init.js,/sw.js,/manifest.webmanifest,/icons/. For/approve/and/api/approve/enteraccess_log off;in the gear field (the links contain one-time tokens).Test over mobile data:
https://asm.example.de/must return 403, an approval link must work. If the access list in your NPM version also applies to the custom locations, use option B.
Option B (Advanced tab of the proxy host, no access list on the host):
location ~ ^/(api/)?approve/ {
access_log off; # links contain one-time tokens
include conf.d/include/proxy.conf;
}
location ~ ^/(assets/|favicon\.svg$|theme-init\.js$|sw\.js$|manifest\.webmanifest$|icons/icon-(180|192|512)\.png$) {
include conf.d/include/proxy.conf;
}
location / {
allow 192.168.0.0/16;
allow 100.64.0.0/10; # e.g. Tailscale
deny all;
proxy_buffering off; # live requests (SSE)
proxy_read_timeout 120s;
include conf.d/include/proxy.conf;
}Also set ASM_TRUST_PROXY=1 and ASM_TRUSTED_NETWORKS=192.168.0.0/16,100.64.0.0/10: ASM itself then blocks
all other paths for foreign IPs as well (a second safeguard in case the proxy is misconfigured). With
ASM_TRUST_PROXY=1, only the X-Forwarded-For entry appended by the proxy counts – entries sent by the client
are ignored. The proxy or Docker network (e.g. 172.16.0.0/12) does not belong in ASM_TRUSTED_NETWORKS.
Security:
The notification text is neutral ("New request waiting for approval"), with no secret, project or reason. The content is end-to-end encrypted (Web Push); Apple only sees the target and the time.
Every link contains a one-time token (stored only as SHA-256). It is valid only for that request, only while it is pending, and becomes worthless after a decision – whether made via the link or in the dashboard.
"Approve" requires a passkey of the owner with user verification (Face ID/device PIN). "Deny" works without one. No session, no cookie, no secret values; 30 calls per minute and IP.
Push subscriptions are only accepted for known push services (Apple, Google FCM, Mozilla, Windows).
ASM does not write the tokens to its log. The proxy's access logs, however, do contain the links – turn them off for
/approve/and/api/approve/(see above).Decisions appear in the audit log as usual (
request.approved/request.denied) withvia: push.A standing approval proposed by an agent also arrives as a push ("A device asks for standing access"). Its page (
/approve/standing/…) lets you narrow the proposal before "Approve" (passkey with Face ID); "Deny" works without one.
Connecting Claude Code
claude mcp add --transport http asm https://asm.example.com/mcpOn first use, Claude Code opens the browser: sign in, check the pairing, "Approve". After that, Claude can
search secrets (search_secrets), request them (request_secret + await_request), create them, propose
changes and archive them, and – for genuine, repeated need – propose a standing approval for its device
(request_standing_approval, then await_request with the srq_… id). asm mcp-config prints the matching command for your server.
CLI
Install directly from your own ASM server (requires Node ≥ 22.12 plus curl or wget; no sudo,
no GitHub or npm access needed):
curl -fsSL https://asm.example.com/cli/install.sh | sh
# without curl: wget -qO- https://asm.example.com/cli/install.sh | sh
asm login https://asm.example.comThe script downloads the CLI bundle (/cli/asm.mjs), verifies SHA-256 and size against /cli/asm.json (this
requires sha256sum, shasum or openssl) and installs it to ~/.local/share/asm/asm.mjs
(different location: ASM_HOME). The command ~/.local/bin/asm (different directory: ASM_INSTALL_DIR) is created
as a symlink to it; the .mjs extension ensures Node always loads the file as an ES module. An
existing asm – including a symlink to a repo build – is replaced. If the directory is not on the
PATH, the script prints a hint. Example with custom paths:
curl -fsSL https://asm.example.com/cli/install.sh | ASM_HOME=/opt/asm ASM_INSTALL_DIR=$HOME/bin shThis way the CLI version always matches the server version; asm update later fetches the current bundle from the server
(also hash-verified), and asm --version shows the installed version. To uninstall, remove both:
rm ~/.local/bin/asm ~/.local/share/asm/asm.mjs.
The CLI stores tokens in the OS keychain: on macOS in the Keychain (security), on Linux via
secret-tool (libsecret, e.g. package libsecret-tools). If neither is available (e.g. on a
server without a desktop session), asm --insecure-store login … stores the tokens in a file with
permissions 0600 instead.
For developers – build from the repo:
pnpm install
pnpm --filter @asm/shared build && pnpm --filter @asm/cli build
ln -s "$PWD/apps/cli/dist/index.js" ~/.local/bin/asm # directory must be on the PATHThe build is plain JavaScript (no tsx, no type stripping); node apps/cli/dist/index.js works
too. pnpm --filter @asm/cli bundle creates the single-file bundle apps/cli/dist-bundle/asm.mjs (+ asm.json),
which a locally started server serves automatically under /cli/ (otherwise set ASM_CLI_DIR).
Usage:
asm login https://asm.example.com # pair device (approve in browser, optionally link it to Claude Code), tokens in the OS keychain
asm search github # metadata only
asm run --grant grt_… -- npm run deploy # value only for this process, as an env variable
asm run --secret sec_… --reason "Deploy" -- ./deploy.sh # request, wait for approval, run
asm write --grant grt_… .env # write to a dotenv file (0600, merged)
asm set --new --title "Stripe Key" --description "Stripe live API (payments)" --env STRIPE_KEY \
--reason "new project" --from-env STRIPE_KEY
asm set sec_… --reason "Key rotated" --from-stdin --wait # propose a change (needs approval)
asm archive sec_… --reason "replaced by sec_…"The project defaults to the name of the Git repo or folder (--project overrides it).
Notes on dotenv files (asm write)
Values are wrapped in double quotes;
\,",$and`are escaped with\.Line breaks are written as a literal
\n. When sourced viash(set -a; . ./.env), this becomes a backslash followed byn, not a line break.The npm package
dotenvconverts\ninto a line break but keeps\$and\`literally. For values containing these characters, preferasm run.
Development
Requirements: Node.js ≥ 24 (LTS), pnpm 11 (version from packageManager in package.json).
pnpm install
pnpm test # unit and integration tests for all packages (vitest)
pnpm typecheck
pnpm build # shared → dist, server → dist (incl. SQL migrations), web → dist, cli → dist
pnpm e2e # Playwright against the built server (once: pnpm exec playwright install chromium)Server in dev mode (TypeScript directly, @asm/shared from source via the development export condition):
cd apps/server
ASM_PUBLIC_URL=http://localhost:5173 ASM_MASTER_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('base64'))") \
ASM_DATA_DIR=./.data pnpm devWeb UI with Vite: pnpm --filter @asm/web dev (port 5173). Vite proxies /api, /oauth, /.well-known and
/mcp to http://localhost:8080 (different server: ASM_DEV_SERVER). For this, the server must run with
ASM_PUBLIC_URL=http://localhost:5173, otherwise the origin check and passkeys fail.
pnpm --filter @asm/server start starts the built server (node dist/main.js).
CI & releases
GitHub Actions (.github/workflows/):
CI (
ci.yml) – on every push tomainand every pull request: typecheck, unit tests, web build, CLI bundle, then Playwright e2e (report/traces as an artifact on failure). Newer PR pushes cancel running runs.Docker (
docker.yml) – buildsghcr.io/eltomato89/asmforlinux/amd64and pushes it to the GitHub Container Registry:after successful CI on
main→edgeandsha-<short>on tag
vX.Y.Z(tests run first in the same workflow) →X.Y.Z,X.Y,latestmanually via "Run workflow" (
workflow_dispatch) – only frommainor av*tagprerelease tags (
v1.0.0-rc.1) only get1.0.0-rc.1, noX.Y/latest
Website (
pages.yml) – builds the landing page (apps/site, see its README) and deploys it to GitHub Pages on pushes tomainthat touchapps/site/**. One-time setup: Settings → Pages → Source: GitHub Actions.Dependabot – weekly updates for Actions and npm (minor/patch grouped).
No additional secrets needed: the push uses the automatic GITHUB_TOKEN (packages: write).
New GHCR packages are private by default. The label org.opencontainers.image.source links the package
to the repo (access permissions are inherited from the repo, visibility is not). The server therefore has to log in before
pulling – with a personal access token (classic) with scope read:packages:
echo "$GHCR_PAT" | docker login ghcr.io -u <github-user> --password-stdin
docker pull ghcr.io/eltomato89/asm:latestAlternatively, make the package public in its settings on GitHub ("Package settings" → "Change visibility").
Release:
git tag v0.3.0 && git push origin v0.3.0Note: Actions minutes are limited for private repos; only linux/amd64 is built (the build cache via type=gha
speeds up subsequent builds). For arm64, add it to platforms in docker.yml and re-add
docker/setup-qemu-action.
Backup
Back up
/data/asm.db(while running, e.g. withsqlite3 /data/asm.db ".backup /backup/asm.db", since SQLite runs in WAL mode).Back up the master key separately. The database is worthless without the key, and so is the key without the database.
Limitations (v1)
Single instance only. Live events (SSE), in-progress OAuth authorizations and WebAuthn challenges are kept in memory; no horizontal scaling, and a restart aborts pairings in progress.
Projects are global. Project names (slugs) are shared by all users of the instance. Merging two projects changes the mapping for everyone: the old name then points to the target project, including for other users' agents that use the same name. Merging is only possible if you can see all affected usages.
Hash chain with a gap at the end. The hash chain detects modified or deleted entries in the middle of the log, but not the deletion of the last entries: anyone with write access to the database can cut off the end without the chain check in the audit log noticing. For tamper-evident records, export the log regularly (CSV) or record the latest hash externally.
License
Licensed under the Apache License, Version 2.0. Copyright 2026 Jens Köhler.
Third-party licenses: THIRD_PARTY_NOTICES in the Docker image (/app/THIRD_PARTY_NOTICES) and next to the CLI bundle (/cli/THIRD_PARTY_NOTICES, installed alongside asm.mjs); the web UI serves its own at /THIRD_PARTY_NOTICES.txt. They are generated during the build.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Password vault for AI agents with scoped, user-approved access
Secrets for developers and agents—secure context and workflows without exposing secret values.
Credential isolation for AI agents: placeholder secrets, policy checks, optional human approval.
A vault for .env files and project credentials: one encryption key per project, a second factor before protected values open, an audit row for every reveal, and scoped MCP access for coding agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to securely use real secrets (API keys, database passwords) by requiring human approval for each release, ensuring secrets never enter the model's context.2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to securely inject API keys and secrets into environment files, configs, or commands without the agent ever seeing the secret values.10 npmMIT
- AlicenseAqualityBmaintenanceSecrets manager for AI coding agents. The model only sees secret names; values are injected into the child process at exec time, every command needs your approval in a native dialog, and output is redacted before it returns to the model.21Apache 2.0
- AlicenseCqualityBmaintenanceLocal MCP server for entering API keys outside chat. Deliver secrets to commands or .env files using an inline MCP App or a paired localhost browser.675 npmMIT