Know your wallet.

Each wallet is stored under ~/.vigil/wallets/<wallet-id>/ by default. Set VIGIL_DATA_DIR to relocate the complete Vigil data directory.

The wallet directory contains two different records:

• wallet.json is a strict public manifest: wallet/profile ids, selected chains, an opaque derivation-policy id, and Wick-derived public accounts.
• secret.v1.json is the only accepted recovery-phrase envelope. Its format is wick-secret-v1, encrypted with AES-256-GCM after scrypt with N=2^17, r=8, and p=1. Each envelope uses a random 32-byte salt and 12-byte nonce.

The wallet id and phrase key source are authenticated as additional data. Unknown fields, algorithms, non-canonical encodings, oversized inputs, an incorrect password, or substitution between wallets therefore fail closed. Unlock also re-derives the active public manifest and requires it to match the stored account authority.

Vigil uses owner-only directory/file modes on POSIX and durable temporary-file, sync, and atomic-rename writes for security-bearing files. These controls do not replace full-disk encryption or protected backups.

Mutable password, key, plaintext, and derived buffers owned by the implementation are overwritten on cleanup paths. JavaScript strings, runtime/library copies, crash dumps, swap, and storage snapshots cannot be proven erased.

Wick owns chain identity, address handling, derivation, transaction codecs, signing, submission, and settlement interpretation. Vigil product code is mechanically prevented from importing cryptographic implementations.

The fund-moving interface exposes a prepared-review-staged flow:

1. A CommonToolbox prepares a typed intent, retains the family transaction, and returns an opaque handle plus a structured review.
2. CommonWallet requires that exact retained preparation and rechecks its account, network, review id, fingerprint, expiry, and approval policy.
3. CommonSigner may stage that prepared operation only. It has no arbitrary raw-bytes, message, calldata, or typed-data signing method.
4. A separate signer child parses and commitment-checks the bounded prepared record, verifies profile/account/family authority, signs its owned plan, and locally verifies the assembled transaction.
5. Only the toolbox that owns the preparation may consume the one-shot staged handle for submission. Status and settlement stay inside Wick.

The signer child is launched without network authority. Requests are bound to the wallet, public profile manifest, session, lifecycle epoch, operation, deadline, and canonical content commitment. Lock, replacement, timeout, policy failure, child exit, or daemon shutdown removes executable authority.

This separate process narrows the useful signing surface; it is not a hardware security boundary. A same-user or privileged host attacker can inspect or alter both processes and their IPC.

1. Back up the recovery phrase offline and verify the backup before funding the wallet. Anyone with it can control the funds.
2. Use a unique wallet password of at least 16 characters (recommended). Vigil accepts 6 or more characters, rejects known breached passwords, and does not require a mix of character types. Memory-hard encryption raises the cost of guessing; it cannot rescue a weak password.
3. Keep the operating system, terminal, and Vigil installation trusted. Use full-disk encryption and protect copies of VIGIL_DATA_DIR.
4. Verify network, asset, destination, amount, fee, and warnings in the review. Clipboard contents and terminal output can be replaced by host software.
5. Use a small test operation before moving a consequential amount, and do not work around an explicit HOLD.

See privacy for local data, network egress, clipboard, and optional diagnostic behavior.

Unavailable capability is reported as unavailable; it is not inferred from a chain name or source directory. Current deliberate HOLDs include:

• Zcash signing because ZIP-243/244 is not implemented; BTC, BCH, DOGE, DASH, and LTC use the reviewed Scure 2.3.0 path and independent vectors;
• NEAR and Harbor fund-moving operations;
• cross-chain routes without a concrete composed provider and settlement port;
• new limit/DCA/trailing creation until the daemon exposes opaque prepare/review/commit handles;
• any operation missing its exact balance, signer, execution, or settlement composition.

GET /health/wick is the running daemon's secret-free readiness source. A catalog entry is not a promise that every operation is live.

Limit, DCA, and trailing orders use explicit state machines and a nonce/CAS claim so only one execution owner may act. The exact Wick review stage is persisted before submission, and returned execution evidence is opaque to Vigil and first-write-wins. These records are daemon-internal; the client has no route that can attach a stage or submission identity.

A definite pre-submit refusal may fail. If submission might have crossed the broadcast boundary, a timeout, crash, lost response, or evidence-persistence failure remains pending/HOLD for query-only reconciliation. Vigil does not blindly submit again and does not decode a chain result as a fallback. A terminal transition requires the live claim identity and a Wick settlement verdict.

Automatic execution additionally requires execution-grade price integrity, including independent-source agreement where the asset policy requires it.

1. Host compromise defeats self-custody. A same-UID or privileged attacker can read unlocked memory, intercept password/phrase input, modify review output, control IPC, replace clipboard contents, or invoke local credentials.
2. JavaScript cannot prove erasure. Owned byte arrays are overwritten, but strings, engine copies, library internals, crash dumps, swap, and OS paging may retain secret material. Scure BIP32 2.4 returns owned private-key copies; Wick transfers or wipes each copy and wipes reachable HD private keys. Scure's internal chain codes and intermediate nodes discarded by derivation remain garbage-collected because its public API cannot explicitly wipe them.
3. The daemon handles sensitive lifecycle input. Wallet creation/import and public-manifest derivation run Wick callbacks in the daemon process. Signer isolation narrows fund-moving authority but does not make the daemon an untrusted process.
4. Process isolation is not a hardware boundary. The signer child shares the same host, user, runtime, binary, and parent-controlled launch environment. Its no-network rule is application-enforced.
5. Password entropy remains decisive. New and replacement wallet passwords require at least 6 characters; 16 or more are recommended. The shared policy rejects known breached passwords, null characters, and inputs over 1,024 UTF-8 bytes; character classes are optional. Scrypt raises cost per guess but cannot rescue a weak or reused password. A recovery phrase restores authority independently of the password.
6. Local auth roots are co-located. The bearer token, wallet-HMAC root, sealed auth state, and encrypted wallet files share the user's data domain. Owner-only modes do not defeat an offline copy by the same user or root.
7. A single endpoint is not consensus. Network identity and response checks catch many failures but cannot make one malicious RPC an independent source of truth. Reorg/finality policy can also be wrong for real conditions.
8. Provider and contract correctness remain financial risks. Local quote, destination, fee, slippage, and commitment checks do not prove provider solvency, contract bytecode, economic fairness, or censorship resistance.
9. Price integrity is not oracle-proof. Independent-source comparison limits accidental/correlated errors but two compromised or correlated feeds can agree on a false price. Single-source assets trade availability for safety by holding automatic execution.
10. Post-submit evidence can remain ambiguous forever. Refusing a blind retry prevents duplicate spending but can require manual investigation and leave an order non-terminal.
11. Non-loopback daemon mode is plaintext HTTP. HMAC/bearer credentials authenticate but do not encrypt. A TLS proxy is required before exposure to an untrusted network.
12. Clipboard and display are external channels. OSC 52 traverses the terminal connection, host clipboard managers may retain history, and a terminal may render confusable text. Verify destination, network, asset, amount, and fees through an independent channel when stakes justify it.
13. File deletion is not erasure. Copy-on-write filesystems, SSD wear levelling, snapshots, backups, and journals can retain deleted ciphertext or local metadata. Use full-disk encryption and protect backups.
14. Optional diagnostics are best-effort redacted. Typed schemas and the redactor reduce leakage but cannot prove arbitrary error messages contain no sensitive information. Review drafts and endpoints before enabling send.
15. Artifact signatures depend on key custody. A pinned public key prevents unsigned bucket replacement, not compromise of the source, compiler, trusted build host, maintainer workstation, or release signing key.
16. Notification account checks are not a profile-mutation lock. A profile can change after the commit-time readiness check and before the SQLite transaction. The forced notify mode carries no signer or provider authority, so this can leave a stale notification but cannot move funds. Fund-moving orders still require one shared wallet/account mutation lock plus a durable signer policy before activation.
17. Pricing timeouts do not cancel transport work. A timed-out caller may retry while the original CoinGecko/Coinbase request is still alive. This is primarily an availability/resource risk, but pricing also gates unattended execution and therefore must fail closed under overlap or exhaustion.
18. Advertised capability can exceed effective composition. Catalog, runtime descriptor, adapter, signer, high-level intent, and protocol transport currently have no single generated intersection. A ready label can therefore overstate a product operation even when the eventual prepare or network call fails closed.
19. A pre-submit checkpoint can remain unknown indefinitely. A crash after checkpointing but before broadcast leaves exact evidence that must not be retried. Runtime rebinding performs query-only reconciliation, but an authoritative not-submitted terminal state and user recovery ceremony are not yet modeled, so the record remains fail-closed unknown.
20. Catalog migration cannot preserve unsupported accounts. Unlock holds a whole wallet if any persisted selection is catalog-only or no longer catalogued. Repair can remove those public accounts and labels only when at least one derivable selection remains and no live or ambiguous order references them. Such an order leaves the wallet on HOLD because no authenticated pre-unlock cancellation/reconciliation ceremony exists; it is never auto-cancelled. An all-held wallet requires on-screen recovery- phrase export and import as a new wallet. The old wallet id, factors, profiles, labels, and history are not transferred automatically.
21. Staging-directory cleanup is a heuristic, not a lock. A killed create writer may leave an owner-only directory containing the encrypted secret envelope and public wallet metadata. Wallet discovery ignores it, and every scan() — so every listing and creation-cap check — now sweeps such directories on a best-effort basis: only names matching the staging pattern are considered, and one is removed only once its mtime is older than ten minutes. A younger directory is left alone because it may belong to a create still in flight in another process, so litter does persist for that window and a machine that never lists wallets again keeps it indefinitely. Staleness is wall-clock relative, so a forward clock jump larger than the bound can make an in-flight staging directory look stale, while a backward jump only defers the sweep. There is still no root-wide cross-process create lock, and the age gate does not replace one; a sweep failure is swallowed rather than failing the listing.
22. Foreign target runtimes are fetched without an independent digest. Bun.build({ compile: { target } }) downloads the matching stable Bun for each cross-compiled target from the npm registry over TLS and Vigil verifies nothing beyond that transport. The environment guard stops a configured redirect, proxy, or disabled certificate check on the build host; it does not defend against a compromised registry, TLS root, or a runtime substituted on the build host itself. Same-target executables embed the running Bun, which the floor and prerelease gates verified.

Vigil has no remote wallet account and sends no analytics by default. Wallet state lives in the configured local data directory (~/.vigil/ unless VIGIL_DATA_DIR is set). Using a wallet still creates network metadata: configured blockchain RPCs, price sources, and any explicitly composed route provider see the requests sent to them. The TUI performs no automatic release check.

The static Vigil website is separate from the local wallet runtime. The explicitly selected theme, intensity setting and ambient CRT-effects switch are saved in browser local storage only. They contain no visitor identifier and are not transmitted. The first-visit greeting uses an anonymous browser-cache marker; clearing cached files replays it independently of these preferences.

Ordinary site access exposes normal connection metadata to its hosting provider. If you submit the optional feedback form:

• the Pages Function receives the selected category, message, optional email, Turnstile token, IP-derived country, user agent, and source IP;
• Cloudflare Turnstile receives the challenge token and source IP for verification;
• when configured, a one-hour per-IP counter may be stored in Cloudflare KV;
• the message, category, optional email, country, and user agent are filed in Linear.

The Function does not keep a second application database copy. Cloudflare and Linear retention and access are governed by those services. Do not send wallet secrets through feedback or email.

Opening the website with ?debug=dial explicitly enables a local brightness control diagnostic panel. It records browser/viewport details, loaded asset names, the dial's layout/styles and bounded interaction/mutation history in page memory. It does not read wallet data, cookies or form contents, and does not send or persist a report. The copy control writes the report to the clipboard only when selected; closing the panel stops collection. Ordinary visits do not load the diagnostic helper.

To arrange a private security report, use the website feedback form with a contact email and a short, non-sensitive description. Wait for a reply before sending exploit details or reproduction files. If the form is unavailable, try again later; do not disclose the issue publicly.

The feedback form uses Cloudflare and Linear as described in Privacy. Never include a recovery phrase, private key, wallet password, live token, or unredacted wallet data.

Start the daemon first, then open the wallet. vigil is the terminal client; it never starts, stops, or signals vigil-api. A service manager keeps the same-release daemon running for price monitoring, submitted-transaction reconciliation, and the isolated signer-child entrypoint. Closing the client leaves the service running. Starting the daemon does not authorize fund movement.

1. Start the background service

Homebrew — the formula already supplies the service definition:

brew services start vigil

Curl on macOS — create ~/Library/LaunchAgents if needed, then save the installer's printed plist as ~/Library/LaunchAgents/dev.r5n.vigil-api.plist. Enable it with:

launchctl bootstrap "gui/$(id -u)" ~/Library/LaunchAgents/dev.r5n.vigil-api.plist

Curl on Linux — create ~/.config/systemd/user if needed, then save the installer's printed unit as ~/.config/systemd/user/vigil-api.service. Enable it with:

systemctl --user daemon-reload
systemctl --user enable --now vigil-api

Optionally run loginctl enable-linger to keep the Linux user service running after logout.

The curl installer writes only to the install directory (default ~/.local/bin, or VIGIL_INSTALL_DIR). It prints the service configuration and commands; it does not save or run them. The recipe uses your exact binary paths. A VIGIL_VERSION override must be 0.10.4 or later, the first release whose archive carries the verified RELEASE-IDENTITY.json.

Manual archives or other supervisors — configure launchd, systemd, runit, or s6 to supervise the exact installed vigil-api executable. Use the installer's printed recipe as a reference. Run vigil-api in the foreground only for diagnostics.

A supervised daemon does not inherit exports from your current shell. Put custom settings such as VIGIL_DAEMON_PORT and VIGIL_DATA_DIR into the plist's EnvironmentVariables dictionary or the unit's Environment= lines too. The client and daemon must agree on these values; see Configuration.

2. Check the service and open Vigil

vigil daemon status
vigil

The status command is read-only. Exit code 0 means running and trusted, 1 means no daemon is running, and 2 means a daemon is present but incompatible or not answering. The client shows API offline when it cannot connect. Use vigil --version to inspect the installed client version.

After upgrading, restart the service so both executables run the same release:

3. Create or import a wallet

Choose Create Wallet, set a strong password, and securely back up your recovery phrase, or import an existing phrase.

Installed release binaries transact on mainnet out of the box. Turn this off in Settings → Mainnet Execution to disable sends, or override it with VIGIL_MAINNET_EXECUTION (see below). Source/dev runs default to mainnet execution off. Always back up before unlocking a live wallet.

Connect Codex, Claude Code or Hermes

Vigil gives a local MCP client short-lived access to one unlocked wallet profile. Read-only access is the default. Transfer proposals require a separate permission and your review and typed approval in Vigil; MCP tools cannot unlock, reveal secrets, approve, sign or broadcast.

1. Run the matching Vigil daemon and TUI using the installation guide. Unlock the intended wallet and select its profile.
2. Open Settings → Agent Access, press n, name the connection and review its permissions. Select 1 Codex, 2 Claude Code, 3 Hermes or 4 Generic JSON. The default is Read only for 15 minutes, with Codex selected. p enables transfer proposals; t selects 15 or 60 minutes. Enter creates the grant.
3. Press c to copy the selected client's configuration. You can change the client format on the issued screen without creating another grant. Merge the Vigil entry into the private configuration described below, preserving the client's other settings. The examples contain placeholders; use the command, token and port copied by Vigil.
4. Restart or reload that client, then ask it to call vigil_status. Check the returned wallet scope, permission and expiry before using vigil_accounts or vigil_portfolio. MCP discovery or a connected indicator alone does not verify the grant.
5. When finished, press Esc to return to the access list, select the grant and revoke it with x. Locking the wallet, changing its session/profile or restarting the daemon also ends access.

The copied configuration contains a secret token. Keep it in a private file outside shared repositories, with owner-only permissions, and out of chat, screenshots, logs and shell command arguments. Clipboard clearing is attempted after 60 seconds; clipboard history can retain the token. Vigil does not install clients or edit their existing configuration files. If copying is unavailable, enable terminal clipboard support and retry c while the issued screen is still open. Alternatively, go back to the list, select this grant and revoke it before creating another.

The client, bridge and daemon must run where the bridge can reach the daemon's local loopback interface. A cloud agent or separate container cannot reach a host daemon through its own 127.0.0.1. The bridge has no remote-daemon URL option and neither starts nor unlocks the daemon. Use the copied absolute executable path; do not substitute a command downloaded by an agent.

Codex

Merge the copied TOML entry into ~/.codex/config.toml, or the private configuration for the Codex host you use:

[mcp_servers.vigil]
command = "/absolute/path/to/vigil-api"
args = ["mcp"]

[mcp_servers.vigil.env]
VIGIL_AGENT_TOKEN = "<one-time scoped token from Vigil>"
VIGIL_DAEMON_PORT = "51911"

Restart the Codex CLI session after changing the entry. In desktop MCP settings, save the server and select Restart; the IDE extension has Restart extension. /mcp shows the active servers. Then call vigil_status to verify wallet access. Avoid token-bearing project .codex/config.toml files and token values in codex mcp add --env arguments. See the official Codex MCP reference.

Claude Code

Save the copied JSON in a private file, for example /absolute/path/to/private-vigil-mcp.json:

{
  "mcpServers": {
    "vigil": {
      "command": "/absolute/path/to/vigil-api",
      "args": ["mcp"],
      "env": {
        "VIGIL_AGENT_TOKEN": "<one-time scoped token from Vigil>",
        "VIGIL_DAEMON_PORT": "51911"
      }
    }
  }
}

Launch Claude Code with the file path, which contains no token:

claude --mcp-config /absolute/path/to/private-vigil-mcp.json

Use /mcp to inspect or reconnect the server, then call vigil_status. After replacing the token in the file, restart Claude Code with the same --mcp-config argument. Keep this file out of shared project .mcp.json configuration. Do not replace ~/.claude.json with this snippet; that file can contain other client settings. Claude Code MCP reference.

Hermes Agent

Merge the copied YAML entry into the active Hermes profile's configuration, normally ~/.hermes/config.yaml. If mcp_servers already exists, add or replace only its vigil entry:

mcp_servers:
  vigil:
    command: "/absolute/path/to/vigil-api"
    args: ["mcp"]
    env:
      VIGIL_AGENT_TOKEN: "<one-time scoped token from Vigil>"
      VIGIL_DAEMON_PORT: "51911"

hermes mcp test vigil checks MCP connection and discovery. Start a fresh Hermes session or use /reload-mcp after configuration or token changes, then call vigil_status to verify the grant. If you use named profiles, configure and test the same profile that will use Vigil. Keep the default serial tool execution; the daemon permits one portfolio read at a time per grant. See the official Hermes configuration reference, reload guide and CLI commands.

Other local MCP clients

Generic JSON uses the same mcpServers wrapper shown for Claude Code. Use it only where the client accepts that format, and follow that client's private configuration and restart instructions. The connection is stdio, with command, args and env; it is not an HTTP URL or an OAuth login. Configure VIGIL_AGENT_TOKEN only for this MCP process, not as a daemon service credential. Never substitute VIGIL_AUTH_TOKEN, a wallet password or a phrase.

Reconnect, replace or remove access

There is no automatic grant renewal. After expiry, revocation, a wallet/profile session change or daemon restart, unlock the intended wallet, create a fresh grant, replace the old client entry and restart or reload the client as above. The old token cannot recover access. If a live grant is being replaced, revoke it first. The token is available only on the issued screen; leaving that screen means creating a new grant if you need another copy.

To remove configuration, use codex mcp remove vigil, or hermes mcp remove vigil. For the Claude Code private-file setup, stop launching with that file and remove its Vigil entry or delete the dedicated file. For a Claude server registered through its CLI, claude mcp remove vigil removes that registration. Revoke in Vigil as well. Removing configuration does not erase copies retained in clipboard history or backups.

Tools and a transfer walkthrough

A proposal input uses exact decimal strings and opaque account/asset ids:

{
  "requestId": "request_example_0001",
  "intent": {
    "accountId": "<accountId from vigil_accounts>",
    "assetId": "<canonical assetId from vigil_portfolio>",
    "amount": "0.001",
    "destination": "<recipient address checked by the owner>",
    "maximumFeeAmount": "0.0001"
  }
}

The fee ceiling is in the chain's native fee asset, not dollars. This is a shape example, not a fee recommendation. Unsupported assets, addresses, endpoints, network policy or signer capability stay on HOLD through Wick's existing validation.

The owner refreshes Agent Access with r, selects the proposal and presses Enter to inspect it. v obtains the canonical review through the ordinary interactive execution service. The screen shows the full account, network asset, amount, destination, fee asset, estimated fee, fee ceiling, warnings, expiry and review fingerprint; arrow and page keys scroll the details. After checking them, a opens a native input requiring the exact displayed SEND … phrase. x rejects without sending. The authenticated TUI submits the retained fingerprint; it cannot replace the proposal's intent during approval.

MCP client -> local bridge -> daemon: propose exact intent + request id
Daemon -> MCP client: pending proposal, no signing authority
Owner -> Vigil: inspect proposal and request preparation
Daemon -> Wick -> owner: canonical bounded review
Owner -> Vigil: typed approval of that retained review
Daemon -> Wick: consume preparation once, persist before submission
Wick -> daemon: submitted or unknown
Owner -> Transaction History: check the outcome before any further action

Expiry, retries and limits

Grants and proposals are memory-only. A proposal expires after five minutes or at grant expiry, whichever comes first; the prepared review can expire sooner. There are at most eight live grants, sixteen retained proposals per grant and 128 globally. Agent requests are limited to thirty per minute per grant, with one portfolio read at a time per grant. Rejected proposals still occupy their idempotency slot until the grant deadline, so rejection cannot create an unbounded proposal stream.

After a lost proposal response, reuse the same request id and identical intent. A changed intent conflicts. Approval obtains one synchronous execution owner before awaiting any work; a repeated approval reports that existing state. Revoking access does not cancel a transfer already approved and in flight.

submitted means broadcast, not confirmed settlement. unknown, a lost approval response or a missing proposal is not proof that no transfer happened. Check Transaction History in Vigil before doing anything further. Do not recreate the transfer with a new request id. The interactive service's durable submission evidence survives daemon restart; the proposal list and grant do not. Create a fresh grant only after unlocking again.

Security boundary and next capabilities

The guarantee is that these MCP tools do not return wallet secrets or grant signing authority. A coding agent with unrestricted shell, file or process access under the wallet owner's OS account can bypass that tool boundary. Keep the wallet directory, daemon credentials, terminal/clipboard channels and wallet processes outside such an agent's OS sandbox, or use a separate OS account with only the scoped bridge accessible. Blocking file reads in a prompt or hiding an export tool is not an OS boundary. Validate the client's actual sandbox and network permissions; MCP installation alone does not establish them. Anthropic likewise distinguishes tool installation from the filesystem/process containment used by its products. Containment guidance.

Portfolio data returned to a client may enter that client's model context and provider retention systems. The local bridge does not make the model local. See Privacy.

Autonomous spending, x402 payments, arbitrary contract calls, swaps and background orders are not enabled by this integration. A later autonomous mode would need owner-set asset/account/recipient allowlists, absolute fee and spending caps, atomic budget reservations, durable idempotency and revocation, and crash/finality evidence across every affected chain family. Model prompts would not enforce those controls. Existing product HOLDs remain in force.

Vigil is licensed under FSL-1.1-ALv2. Each version becomes available under Apache-2.0 on the second anniversary of the date that version was first made available. The change date applies separately to each version.

FSL permits use, copying, modification and redistribution for its permitted purposes. It restricts competing commercial products and services as defined in the licence. The full licence governs these rights, including its notices, conditions and warranty disclaimer.

Source downloads are not available during the current alpha. Source-code access is planned for beta; the delivery details will be published when it is ready. The licence and the availability of a source download are separate facts.