morsec documentation
morsec lets a coding agent use your API keys, database passwords and tokens without ever seeing them. The agent holds references like ms://stripe/test. The values stay in your macOS keychain, and msd, a daemon running as you, adds them at the last moment.
Install
You need an Apple silicon Mac with macOS 13 or later. Every channel installs the same four programs: ms, mors (the same command), msd and ms-shim. They are signed with Developer ID team 554MCRUAKK and notarized.
$ brew install csakash/tap/morsecmsd's LaunchAgent points at Homebrew's stable opt/morsec path, so upgrades are picked up after a restart.
$ npm install -g morsecNeeds an arm64 Node.js 18 or later. The binaries come in morsec-darwin-arm64. Neither package runs anything at install time.
$ curl -fsSL https://github.com/csakash/morsec/releases/latest/download/install.sh | shInstalls into ~/.local/bin (or MORSEC_INSTALL_DIR) without sudo. Before installing, it checks the checksums, their minisign signature when minisign is installed, each code signature and team, and notarization. Add --version 0.1.0 to pin.
Read before you run. Download install.sh, SHA256SUMS and SHA256SUMS.minisig from the release, check them as Verify a download shows, then run sh install.sh.
Quickstart
1. Set up the vault
$ ms initCreates the vault in your login keychain, generates the local certificate authority and starts msd as a LaunchAgent. ms status says whether morsec is on and how many secrets it protects.
2. Add your secrets
Type one in (hidden input), or move a whole .env in. Import shows a review table first, then stores the values and rewrites the file with references.
$ ms add stripe/test --tier test$ ms import .env
Values already in git history stay readable there. Rotate any key that was ever committed, then import the new one.
3. Say where each key may go
$ ms rules stripe/test --add-host api.stripe.com4. Connect your agent and check
$ ms connect claude-code --env STRIPE_API_KEY=ms://stripe/test$ ms doctor ✓ msd identity verified · cc.morsec.msd · team 554MCRUAKK ✓ claude-code routes through morsec
Start a new agent session. It sees STRIPE_API_KEY=ms://stripe/test. When it calls api.stripe.com, msd swaps the real key in on the way out.
References
A reference is the name of a secret in your vault, written ms://<name>. It is what goes in your .env, your agent's environment and its context window. It's safe to print, paste and commit.
For SDKs that check the format of a key, morsec can hand out a shaped placeholder such as sk_test_ms_… that msd maps back to the reference.
Swap mode, for HTTP APIs
Connectors point the agent's HTTPS_PROXY at msd on loopback. For a host bound to a key, msd:
- terminates TLS with a certificate from your local morsec CA, whose name constraints cover only your bound hosts;
- replaces the reference in the configured place (a header, basic auth or a query parameter);
- strips any other credential the agent added;
- forwards over a fresh TLS connection, and writes a receipt.
A reference sent to a host it isn't bound to is blocked and recorded. Redirects carry no credentials, and cloud metadata and private address ranges are refused.
Run mode, for commands
For tools that aren't HTTP, such as psql, ssh, git and deploy scripts, msd runs the command for the agent. ms-shim sits first on the agent's PATH and hands calls with an ms:// reference to msd; anything else runs the real tool unchanged.
$ ms add db/staging --mode run --tier test$ ms rules db/staging --add-root ~/code/shop --add-env PGPASSWORD \ --add-command '["psql", "**"]'$ ms run --link-shims
- Postgres: the password goes in a 0600 passfile only msd can reach, never in
argv. Read-only rules setdefault_transaction_read_only=on. - SSH: msd is the SSH agent. The private key never leaves it.
- git over HTTPS: msd is a credential helper for the bound host.
Output streams back through a redactor that also catches base64 and URL-encoded forms of the value. In a command pattern, * matches one argument and a trailing ** any number.
Tiers and approvals
test keys never prompt. production keys, the default for ms add, need your approval before each use, once or for the agent session.
The request appears in your terminal (ms approve, or ms approve --watch in a spare one) as plain text built from the real command, and you confirm with Touch ID. The approval is bound to the session, key, argument hash, directory and an expiry. Inside an agent session, ms approve refuses.
Rules
Everything is denied by default. A key does nothing until you give it a target. Loosening a rule asks for Touch ID; tightening doesn't.
| Field | What it does |
|---|---|
hosts | Where a swap-mode key may be sent. |
commands | Which commands a run-mode key may be used with, as argument patterns. |
tier | test or production. |
session_ttl_secs | How long a session approval lasts. |
read_only | Run database commands in a read-only transaction. |
disabled | Turn a key off without deleting it. |
A project's .morsec.toml can only tighten your rules for that repository.
Receipts
Every use, allowed or blocked, is one record: time, agent, session, key, mechanism, host or command, a hash and redacted copy of the arguments, the rule version, the approval and the result. Records are hash-chained and MAC'd with a vault key.
$ ms log --since 2h --result blocked$ ms log --verify ✓ chain intact
Claude Code
Works in the terminal, the desktop app and the IDE extensions.
$ ms connect claude-code --env STRIPE_API_KEY=ms://stripe/test --dry-run$ ms connect claude-code --env STRIPE_API_KEY=ms://stripe/test
The connector sets the agent's environment and proxy, and puts ~/.morsec/shims first on its PATH for run mode. Add --with-mcp to expose your run commands as MCP tools. ms disconnect claude-code undoes it.
Codex
$ ms connect codex --env STRIPE_API_KEY=ms://stripe/testSets Codex's shell environment policy, network proxy and an mcp_servers.ms entry. For run mode, have Codex call ms run -- <command> or use the MCP tools.
MCP
ms mcp is a stdio MCP server that turns your run commands into typed tools, such as db_query or deploy_staging. It's a thin client of msd and never holds a value.
Cursor and Gemini connectors are next. planned
Commands
ms and mors are the same program.
| Command | What it does |
|---|---|
ms init | Create the vault and start the daemon. |
ms add | Add a secret (hidden input, or --stdin). |
ms import | Move a .env into the vault and rewrite it with references. |
ms rules | Show or change a key's hosts, commands, tier and session length. |
ms connect | Set up a coding agent. ms disconnect removes it. |
ms run | Run a command with references resolved by the broker. |
ms approve | Answer the request waiting for your approval (Touch ID). |
ms log | Show receipts. --verify checks the chain, --export for a review. |
ms stop | Revoke every grant now and kill running commands. ms start resumes, with Touch ID. |
ms status | Show whether morsec is on. |
ms doctor | Check that every connected agent routes through morsec. --live checks from inside the agent. |
ms mcp | Run the MCP server for an agent. |
ms scan | Scan agent transcripts for leaked secret values. |
ms stats | Prompts per session, blocks and approvals. |
Security model
On macOS the agent and msd run as the same Unix user, so every control assumes the agent can read your files and reach the daemon's socket.
| An agent tries to | Why it fails |
|---|---|
| Read a value from the keychain | Items are bound to msd's code signature: identifier cc.morsec.msd plus the release team. Another program, or a replaced msd, can't read them. |
| Read msd's memory | Hardened runtime without get-task-allow. Values are zeroized after use. |
| Loosen the rules file | Rules are MAC'd with a vault key; a bad MAC is rejected. Loosening needs ms rules and Touch ID. |
| Fake an approval | Prompts come from the real exec plan, on your terminal, with Touch ID. Callers inside an agent session can't approve. |
| Pose as msd | A signed ms checks msd's signature and that msd alone holds the socket. |
| Rewrite receipts | Hash-chained and MAC'd; ms log --verify finds the edit. |
| Skip the proxy | It never had a value, so it only loses access. ms doctor reports the drift. |
Known limit. In run mode, a same-user process could read a child command's environment or passfile while it runs. morsec prefers protocols that never put the value in a child (SSH agent, git credential helper) and keeps passfiles short-lived. Running children as a separate user is on the roadmap.
The full threat model maps 60 threats to the tests that cover them: docs/threat-model.md.
Upgrading
There is no auto-update. Upgrade with the channel you installed with, then restart msd:
$ brew upgrade morsec # or npm install -g morsec@latest, or the curl installer$ launchctl kickstart -k gui/$(id -u)/cc.morsec.msd
After a curl upgrade, also run ms run --link-shims. If you switch Node versions with nvm, fnm or volta, install morsec under the new one, run ms init and reconnect your agents.
Verify a download
$ shasum -a 256 -c SHA256SUMS$ minisign -Vm SHA256SUMS -P RWRTLFpql8eLhPWagccY08QMJqtuPerVZ/+xpw9LVkhRCC3/79D4vmFy$ codesign --verify --strict ms msd ms-shim$ spctl -a -vv -t install msd source=Notarized Developer ID origin=Developer ID Application: Akash Munshi (554MCRUAKK)
The minisign public key is also committed at packaging/minisign.pub. The full steps are in packaging/VERIFY.md.
Troubleshooting
Start with ms doctor. It checks the daemon, the vault, the run shims and every connected agent, and each failure says what to run.
| You see | Do this |
|---|---|
daemon not running | ms start, or check ms doctor. |
| A request to a new host is blocked | ms rules <key> --add-host <host>, then retry. |
| The agent still sees an old value | Start a new agent session after ms connect. |
| msd doesn't start after an upgrade | launchctl kickstart -k gui/$(id -u)/cc.morsec.msd |