Start / Overview

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.

Fig. 1 — agent · morsec · bound host · unknown hostlive
Start / Install

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/morsec

msd's LaunchAgent points at Homebrew's stable opt/morsec path, so upgrades are picked up after a restart.

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.

Start / Quickstart

Quickstart

1. Set up the vault

$ ms init

Creates 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.com

4. 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.

Concepts / References

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.

Concepts / Swap mode

Swap mode, for HTTP APIs

Connectors point the agent's HTTPS_PROXY at msd on loopback. For a host bound to a key, msd:

  1. terminates TLS with a certificate from your local morsec CA, whose name constraints cover only your bound hosts;
  2. replaces the reference in the configured place (a header, basic auth or a query parameter);
  3. strips any other credential the agent added;
  4. 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.

Concepts / Run mode

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 set default_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.

Concepts / Tiers and approvals

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.

Concepts / Rules

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.

FieldWhat it does
hostsWhere a swap-mode key may be sent.
commandsWhich commands a run-mode key may be used with, as argument patterns.
tiertest or production.
session_ttl_secsHow long a session approval lasts.
read_onlyRun database commands in a read-only transaction.
disabledTurn a key off without deleting it.

A project's .morsec.toml can only tighten your rules for that repository.

Concepts / Receipts

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
Agents / Claude Code

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.

Agents / Codex

Codex

$ ms connect codex --env STRIPE_API_KEY=ms://stripe/test

Sets 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.

Agents / MCP

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

Reference / Commands

Commands

ms and mors are the same program.

CommandWhat it does
ms initCreate the vault and start the daemon.
ms addAdd a secret (hidden input, or --stdin).
ms importMove a .env into the vault and rewrite it with references.
ms rulesShow or change a key's hosts, commands, tier and session length.
ms connectSet up a coding agent. ms disconnect removes it.
ms runRun a command with references resolved by the broker.
ms approveAnswer the request waiting for your approval (Touch ID).
ms logShow receipts. --verify checks the chain, --export for a review.
ms stopRevoke every grant now and kill running commands. ms start resumes, with Touch ID.
ms statusShow whether morsec is on.
ms doctorCheck that every connected agent routes through morsec. --live checks from inside the agent.
ms mcpRun the MCP server for an agent.
ms scanScan agent transcripts for leaked secret values.
ms statsPrompts per session, blocks and approvals.
Reference / Security model

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 toWhy it fails
Read a value from the keychainItems 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 memoryHardened runtime without get-task-allow. Values are zeroized after use.
Loosen the rules fileRules are MAC'd with a vault key; a bad MAC is rejected. Loosening needs ms rules and Touch ID.
Fake an approvalPrompts come from the real exec plan, on your terminal, with Touch ID. Callers inside an agent session can't approve.
Pose as msdA signed ms checks msd's signature and that msd alone holds the socket.
Rewrite receiptsHash-chained and MAC'd; ms log --verify finds the edit.
Skip the proxyIt 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.

Reference / Upgrading

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.

Reference / Verify a download

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.

Reference / Troubleshooting

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 seeDo this
daemon not runningms start, or check ms doctor.
A request to a new host is blockedms rules <key> --add-host <host>, then retry.
The agent still sees an old valueStart a new agent session after ms connect.
msd doesn't start after an upgradelaunchctl kickstart -k gui/$(id -u)/cc.morsec.msd