Sigil

sigil

Claude can sign, but never see.

sigil is a local signing tool and Claude Code integration that lets agentic coding tools use private keys without ever putting key material in the model's context window.

Status: pre-alpha. The MCP server, CLI, unlock flow, ward hooks, policy engine (static checks), out-of-band confirmation via ntfy, Solana signing, and the JSON-RPC signing proxy (Foundry/Hardhat) all work end-to-end. Rolling-window value caps and EIP-712 domain allowlists landed in the policy engine, but have not been through a release yet. Until v0.1.0 ships — with the supply-chain attestations promised for it — do not use this with real funds yet. Build plan lives in the tracking issue.

What it is

One MCP server process, four bins (plus a legacy sigild alias), six runtime deps (all pinned, zero transitive):

1. sigil-mcp — the only thing that runs. Claude Code spawns it per session via your mcpServers config; it dies when Claude exits. Holds unlocked keys in process memory (zeroized on shutdown, sigil lock, or unlock-failure; mlock against swap is planned). Keys at rest are encrypted with XChaCha20-Poly1305 and an Argon2id-derived key. Signs over stdio using a DIY MCP wire protocol (~200 lines, no SDK dep). Claude never sees key material — only opaque handles like evm:executor.
2. sigil — control CLI. init, status, portal new/add/list/qr/remove, policy show/init, unlock, lock.
3. sigil-hook-pre / sigil-hook-post — Claude Code hook binaries that block reads of common key paths and redact key-shaped strings from tool output.

sigil-mcp boots locked: empty in-memory handle table, no keys loaded. Sign methods return DAEMON_LOCKED (-32003) with a "run sigil unlock" message until you push the passphrase in from a separate terminal via sigil unlock. That CLI connects to a per-session Unix socket at ~/.sigil/control/<pid>.sock (0600) that sigil-mcp opens at startup — and fans out to every such socket so one sigil unlock reaches all open windows. After unlock, signs work for the rest of the session; sigil lock zeroizes the table without killing the process.

Sign methods exposed today: EIP-191 personal_sign, EIP-1559 + legacy transactions, EIP-712 typed data, plus Solana (ed25519) message + transaction signing — see Solana support below.

What it isn't

• Not a hardware wallet replacement. If you can use a Ledger or YubiKey, do that.
• Not a custody solution. It runs on your laptop or VPS and protects you from one specific class of failure: leaking key material through an LLM agent.
• A first cut of bounding signing authority via the policy engine — but not the full thing. Shipped: static checks (chain ID, destination allowlist, per-tx value cap, function-selector allowlist, contract-creation gating, on/off toggles for personal_sign and EIP-712) plus out-of-band human confirmation via ntfy. Rolling-window caps and EIP-712 domain allowlists are tracked in #3 and will land incrementally.

Install

npm install -g sigild

This drops four binaries on your $PATH: sigil, sigil-mcp, sigil-hook-pre, sigil-hook-post (plus sigild, a legacy alias for sigil-mcp). (The package name on npm is sigild for legacy reasons; the bins do not include a daemon any more.)

Requires Node 22+, macOS or Linux. (The CLI ↔ session control channel uses Unix domain sockets; Windows is untested and currently unsupported.)

Quick start

# 1. Wire sigil into Claude Code (project-scoped). Pass --user to do it globally.sigil init
# 2a. Generate a fresh key inside sigil (no plaintext ever hits disk):sigil portal new evm:bot# → prompts for a passphrase, mints a fresh secp256k1 key, prints the#   address, writes ~/.sigil/keys/evm:bot.sigil + permissive policy.## 2b. OR import an existing private key from a file:#     Accepts either 32 raw bytes or 64 hex chars (with optional 0x prefix).sigil portal add evm:bot --key-file ./private.hex# → same as above but seeded from the file. Source file is deleted by#   default (pass --no-remove-source to keep it).## Either form: pass --strict to start with a locked-down policy template# you fill in before any sign succeeds.
# 3. Open Claude Code. It spawns sigil-mcp automatically via your MCP config.#    sigil-mcp boots locked — the first sign attempt will return DAEMON_LOCKED.
# 4. In a separate terminal, push the passphrase to every running sigil-mcp.sigil unlock# → prompts once, decrypts every keyfile in ~/.sigil/keys/ into each open window
# 5. Use Claude Code. The sigil_* tools (EVM + Solana) will work for the rest of the session.
# Optional: re-lock without restarting Claude.sigil lock

If you close Claude Code, sigil-mcp exits and its memory is wiped. Open a new session and sigil unlock again — the encrypted keyfiles on disk persist.

CLI reference

sigil init [--user]  Project scope: writes the ward hooks to <cwd>/.claude/settings.json  and the MCP server registration to <cwd>/.mcp.json.  --user: writes hooks to ~/.claude/settings.json and the MCP server  registration to ~/.claude.json. (Claude Code CLI reads MCP configs  from .mcp.json / ~/.claude.json — not from settings.json.)  Idempotent — preserves your unrelated settings, and on upgrade  migrates any stale mcpServers.sigil entry out of settings.json.
sigil portal new <handle> [--strict]  Generate a fresh secp256k1 key inside sigil, encrypt with your  passphrase, write it to ~/.sigil/keys/<handle>.sigil (mode 0600).  No plaintext key ever lands on disk. Use this when you want a clean  hot wallet for a bot (vs importing an existing key from a file).  Also writes ~/.sigil/policy/<handle>.toml — permissive by default,  or --strict for a locked-down template.
sigil portal add <handle> --key-file <path> [--no-remove-source] [--strict]  Import an existing private key. Encrypts it with your passphrase  and stores at ~/.sigil/keys/<handle>.sigil (mode 0600). Handle  format is <kind>:<name> where kind is "evm". The source key file  is deleted by default — pass --no-remove-source to keep it.  Also writes ~/.sigil/policy/<handle>.toml — permissive by default  (signs anything), or --strict for a locked-down template you fill  in before signs succeed.
sigil policy show <handle>  Print the current policy file for a portal. Validates schema; exits  1 if the file is missing or malformed.
sigil policy init <handle> [--strict]  Provision a policy file for an existing portal whose policy is  missing (e.g. a keyfile from an older sigil version, or one you  manually deleted). Refuses to overwrite — edit the file directly  or remove it first. Defaults to permissive; --strict writes the  locked-down template.
sigil rpc init <handle> --upstream <url> [--port <n>]  Enable the JSON-RPC signing proxy for a portal: generates a strong  auth token and appends the [rpc] block to ~/.sigil/config.toml  (refuses if one exists; preserves the rest of the file). Prints the  ready-to-paste authenticated endpoint and forge invocation. Restart  Claude Code sessions to pick it up.
sigil portal list  List the encrypted keyfiles on disk with their derived addresses  (EVM + Solana). Requires the passphrase.
sigil portal qr <handle>  Render a portal's address as a terminal QR code (for funding it from  a phone wallet). Requires the passphrase.
sigil portal remove <handle>  Delete a keyfile from disk.
sigil unlock  Prompt for the passphrase and push it to every running sigil-mcp at  once (one per Claude window). After unlock, sign calls succeed for the  rest of each session. Idempotent — sessions already unlocked are left  as-is. Fails if no sigil-mcp is running (start a Claude Code session  first).
sigil lock  Tell every running sigil-mcp to zeroize and clear its in-memory keys.  Re-unlock with sigil unlock — the sigil-mcp processes keep running.
sigil status  Report which sigil-mcp sessions are running (one entry per window,  with PID, unlocked flag, and loaded portals) and how many keyfiles  exist on disk. Does not require the passphrase.

Set SIGIL_HOME to override ~/.sigil. Set SIGIL_CONTROL_DIR to override the control-socket directory.

Multi-window behaviour

Each Claude Code window spawns its own sigil-mcp, and each binds its own control socket at ~/.sigil/control/<pid>.sock. They share the on-disk keyfiles + audit log but keep separate in-memory handle tables.

sigil unlock / lock / status fan out across every socket in ~/.sigil/control/, so a single sigil unlock loads keys into all currently-open windows — no more guessing which process the CLI reaches. Sockets left behind by hard-killed sessions are detected and cleaned up automatically on the next CLI call.

Each window still holds its own decrypted keys only for its own lifetime: closing a window zeroizes that session's keys, and a window opened after you unlock starts locked (run sigil unlock again to include it). Keys never outlive the Claude sessions that use them — a deliberate property from #23.

OS-keychain integration (planned, v0.3) will make unlock zero-touch for users who set it up.

After upgrading sigil, restart every Claude window's sigil-mcp (reconnect the MCP server or reopen the window, then sigil unlock again). A running sigil-mcp never reloads code, and daemons from different versions must not share ~/.sigil/audit.log: the lock protocol and the writer's chain checks are version-specific. ps -ax | grep sigil-mcp shows stragglers.

Policy engine

Once a portal is unlocked, signing authority over its key is real. To bound the blast radius of a successful prompt injection, every portal has a policy file at ~/.sigil/policy/<handle>.toml. Two modes:

Permissive (default for sigil portal add): no rules. Sign anything the agent asks. The key isolation guarantees still hold — your key never enters the agent's context — but the unlocked portal can be made to sign whatever an attacker can get the agent to ask for. Useful for: testnet bots, demo flows, anyone who only cares about the context-window protection.

Strict (opt in with --strict): every sign request is checked. Generated template:

mode = "strict"
chain_ids = [1]                           # allowed chain IDsallow_to = []                             # allowed destination addresses (lowercase 0x)max_value_wei = "0"                       # per-tx cap, in wei, as decimal stringallowed_selectors = []                    # 4-byte function selectors, e.g. "0xa9059cbb"
allow_contract_creation = false           # deploys (to = null); when true, every                                          # deploy still requires a confirm tap
allow_message_signing = false             # EIP-191 personal_sign (e.g. SIWE)allow_typed_data = false                  # EIP-712 (Permit, OpenSea — can be financial)typed_data_verifying_contracts = []       # when allowed: domain.verifyingContract allowlisttyped_data_primary_types = []             # when allowed: primaryType allowlist ("Permit", …)                                          # strict mode also requires domain.chainId ∈ chain_ids
# Optional rolling-window caps on tx.value (work in permissive mode too).max_value_per_hour_wei = "100000000000000000"    # 0.1 ETH / hourmax_value_per_day_wei = "1000000000000000000"    # 1 ETH / day
# Optional: above this value, sigil pushes a notification to your phone and# waits for an approve/deny tap before signing. See "Out-of-band confirm"# below. Must be strictly less than max_value_wei.require_confirm_above_wei = "10000000000000000"   # 0.01 ETH

A failed rule throws POLICY_DENIED (-32001) back to the agent with the human-readable reason ("tx denied — value X exceeds max_value_wei Y"), and the deny is appended to the hash-chained audit log alongside allows. Denies are forensically the more interesting half — they're the prompt-injection canary.

Rolling-window caps (max_value_per_hour_wei, max_value_per_day_wei, and svm_max_lamports_per_hour/day) are the one rule that applies in both modes — a permissive "bot with an allowance" is the common case. They count native value only: tx.value for EVM, decoded System-Program transfers for Solana. ERC-20 / SPL transfers are calldata, not native value, and are not counted — and require_confirm_above_wei doesn't see them either (a token transfer has value = 0). Gate token movement with strict mode's allow_to + allowed_selectors; for Solana, anything sigil can't decode as a System-Program transfer is routed to confirm in strict mode, and denied outright when a lamport cap is set. Spends are recorded in a per-portal ledger at ~/.sigil/state/<handle>.ledger (append-only JSONL, shared across windows through the same lock as the audit log, compacted automatically) and the check-and-record is atomic, so two windows can't both take the last of an allowance. The cap is checked before any confirm push (so you're not asked to approve something that would be denied anyway) and again right before signing. sigil policy spend <handle> shows the trailing 1h/24h totals against the caps. sigil portal remove deletes the ledger with the portal.

EIP-712 allowlists (strict mode, with allow_typed_data = true): typed_data_verifying_contracts and typed_data_primary_types each restrict one axis when non-empty, and the domain must carry a chainId that names one of chain_ids (strict mode refuses chain-less domains, since they can't be checked). A typed-data signature can move funds (Permit, Permit2, exchange orders), so it gets the same treatment as a transaction's destination.

Still deferred (in #3): decoded-calldata argument checks.

Out-of-band confirm

For sign requests above require_confirm_above_wei, sigil pushes a notification to a channel you control (not the agent) and waits for an explicit human ack before signing. Today the only transport is ntfy — zero-setup, no accounts. SMS and Telegram transports are wired behind the same ConfirmTransport interface and will land in follow-ups.

Wire it up in ~/.sigil/config.toml:

[confirm.ntfy]topic  = "your-unguessable-string-here"     # the topic name IS the credential# server = "https://ntfy.example.com"       # optional, default https://ntfy.sh
[confirm]# timeout_ms = 60000                        # default 60s; timeout = deny

Install the ntfy app on your phone, subscribe to that topic, and you'll get a push with Approve / Deny buttons every time the threshold is crossed. The buttons hit a local 127.0.0.1 listener inside sigil-mcp with a one-time, request-bound token — a leaked or replayed token can't approve a different sign. Timeout, deny click, and push-provider outage all fail closed.

If any policy file sets require_confirm_above_wei but no transport is configured, sigil-mcp refuses to start with a clear error rather than silently degrading every confirm-gated sign to a deny.

JSON-RPC signing proxy (Foundry / Hardhat / any web3 tool)

sigil can expose a local JSON-RPC endpoint that makes any portal a drop-in signer for tooling that expects an unlocked node account — the same pattern Clef and web3signer use. Contract bytecode goes from forge straight into sigil; it never transits the agent's context or an MCP tool parameter.

Enable it with one command (generates the token, writes the config block, prints the forge invocation):

sigil rpc init evm:bot --upstream https://sepolia.example/v3/KEY

...or by hand in ~/.sigil/config.toml:

[rpc]portal   = "evm:bot"                        # which portal signsupstream = "https://sepolia.example/v3/KEY" # real node for everything elsetoken    = "<openssl rand -hex 24>"         # required — guards the endpoint# port   = 8547                             # default 8547 (clear of anvil's 8545)

Then point any tool at it, with the token as the Basic-auth password:

forge script script/Deploy.s.sol \  --rpc-url "http://sigil:<token>@127.0.0.1:8547" \  --unlocked --sender 0xYourPortalAddress --broadcast

The proxy serves three things with the portal key and forwards everything else (eth_call, eth_estimateGas, eth_getTransactionReceipt, …) to the upstream:

• eth_accounts → the portal address (empty while locked)
• eth_signTransaction → fills nonce/gas/fees if missing, signs, returns the raw tx
• eth_sendTransaction → same, then broadcasts via the upstream and returns the hash

Security properties. The listener binds 127.0.0.1 only; every request must present the config token (constant-time compared) and a loopback Host header (DNS-rebinding defence). Signing runs through the identical daemon pipeline as the MCP tools — policy checks, the out-of-band confirm gate, and the hash-chained audit log all apply, so this surface adds a transport, not a privilege. The filled transaction carries the upstream's chain id, so a strict policy's chain_ids allowlist binds the proxy to the network you configured. Message/typed-data methods (eth_sign, personal_sign, eth_signTypedData*) are rejected on this surface — use the MCP tools, which have their own policy toggles. A strict policy with allow_contract_creation = true gives you confirm-gated forge script deploys: forge submits, your phone buzzes, the tx signs when you tap approve.

With multiple Claude windows open, each sigil-mcp tries to bind the port; the first wins and the rest log and continue — any one session's proxy serves the machine.

When the proxy is enabled, sigil-mcp advertises the endpoint — including the authenticated URL — in the sigil_eth_sign_transaction tool description, so the agent discovers it on its own and reaches for forge --unlocked instead of transcribing bytecode through the MCP tool. This is deliberate: the token gates other local software, not your agent (see THREAT_MODEL.md).

Solana (SVM)

Every portal also controls a Solana address, derived from the same secret. EVM uses secp256k1; Solana uses ed25519 — different curves, so you can't share a public key. But the portal's raw 32-byte secret doubles as an ed25519 seed, yielding one secret → two addresses:

$ sigil portal listevm:executor  evm: 0x1234…abcd  svm: 7vWxK…Qm9f          # base58 ed25519 address, same key

This is exactly the derivation Phantom/Solflare perform on "import private key", so the Solana address is recoverable there (it does not match a seed-phrase / BIP44 account — it's the raw-key account).

Two MCP tools:

• sigil_svm_sign_message — sign arbitrary off-chain bytes (e.g. Sign-In With Solana) with the ed25519 key. Input is base64; returns a base58 signature.
• sigil_svm_sign_transaction — pass a serialized Solana transaction message (base64, legacy or v0); sigil ed25519-signs those bytes and returns the base58 signature for you to assemble into the transaction.

Policy. Solana hides most semantics behind account indices and on-chain state, so sigil only decodes what it can offline: native SOL (System Program) transfers, which it gates on svm_allow_to (base58 recipient allowlist) and svm_max_lamports (per-tx cap), exactly like EVM. Anything it can't fully decode — SPL tokens, program calls, address-lookup-table accounts — is routed to the out-of-band confirm gate, never silently allowed. Auto-allow is all-or-nothing: a tx is only signed without a human tap if every instruction decoded and passed policy. require_confirm_above_lamports adds a value threshold (and, in strict mode, the undecodable-tx confirm); in strict mode an undecodable tx with no confirm transport configured fails closed (deny).

Relevant policy fields (~/.sigil/policy/<handle>.toml): allow_svm_message_signing, svm_allow_to, svm_max_lamports, require_confirm_above_lamports.

Supply chain posture

Key-management libraries die from supply chain compromise, not from clever attacks on the code. Given the npm ecosystem in 2026 (Mini Shai-Hulud, Axios, pgserve, TanStack), sigil commits to:

• Zero install scripts. No postinstall, preinstall, prepare. CI-enforced: every PR runs a guard that fails if any package in the resolved tree declares one.
• Six runtime deps, all version-pinned (no caret ranges), all zero-transitive — the entire npm ls --omit dev tree is exactly these six packages:
  • @noble/ciphers for XChaCha20-Poly1305
  • @noble/hashes for Argon2id, keccak256, sha2/sha512, HMAC
  • @noble/secp256k1 for ECDSA (EVM)
  • @noble/ed25519 for EdDSA (Solana)
  • @iarna/toml for parsing per-portal policy TOML files
  • qrcode-generator for sigil portal qr rendering
• No MCP SDK. The official @modelcontextprotocol/sdk pulls 92 transitive deps (ajv, hono, cors, cross-spawn, etc) — unacceptable surface. We implement the MCP wire protocol directly in ~200 lines.
• No Bun. Plain Node only. Bun is currently being weaponized by Mini Shai-Hulud as an evasion layer; we will not give that pattern any cover.
• Provenance attestations on every npm publish. Starting v0.0.4, releases are built by a GitHub Actions workflow under OIDC trusted-publisher auth, signed with a Sigstore attestation. No long-lived npm token; tampered or out-of-band publishes fail signature verification.
• CycloneDX SBOM attached to every GitHub Release. Full transitive dep tree enumerated at release time.
• Install-scripts CI guard. Every PR fails if any package in the resolved tree declares preinstall / install / postinstall. .npmrc already has ignore-scripts=true so these never actually run for us; the guard catches new transitive deps that might run for a user without our .npmrc.
• Still planned for v0.1.0:
  • Signed standalone binaries from GitHub Releases for users who'd rather not touch npm
  • Action SHA pinning rotation via Dependabot

Verifying a release

You can confirm a sigild tarball was built by the public workflow at the commit it claims to come from:

# Validates every package in your install tree:npm audit signatures
# Inspect the attestation for a specific sigild version:npm view sigild@<version> dist.attestations# → shows the workflow filename, the commit SHA, and the Sigstore signing cert

What the attestation tells you: this tarball was built by cdrn/sigil's .github/workflows/release.yml, at a specific commit on main, at a specific time. It does not tell you that commit is non-malicious — for that, read the diff between the version you trust and the version you're upgrading to. But it does mean an attacker who steals an npm token can't publish a malicious sigild under our name; they'd need to compromise the GitHub repo + push a tag, which leaves an audit trail.

Every release also publishes a CycloneDX SBOM as a GitHub Release asset, enumerating every package (direct + transitive) in the install tree at the version pinned by package-lock.json:

# Download + inspect the SBOM for a specific release:gh release download v0.0.4 --repo cdrn/sigil --pattern '*.cdx.json'# → produces sigild-v0.0.4.cdx.json — feed to syft/grype/etc. for vuln scan

Threat model

See THREAT_MODEL.md. Read it before trusting this with anything.

Development

git clone https://github.com/cdrn/sigilcd sigilnpm install      # respects .npmrc ignore-scripts=truenpm test         # builds + runs 600+ tests; should finish in under 15s

See CONTRIBUTING.md for the PR-per-layer workflow.

License

Apache License 2.0. See LICENSE.