WLFI Agentic SDK

WLFI Agentic SDK is a root-managed local signing daemon with policy enforcement, a single wlfi-agent CLI, and an optional relay + web approval flow.

Install

One-click install

The fastest operator path is the interactive bootstrap script:

curl -fsSL https://github.com/wlfi-infra/test/releases/download/one-click-latest/setup-wlfi-agent.sh | bash

The script can:

• let the user choose an install directory
• download a prebuilt macOS runtime bundle instead of compiling Cargo or pnpm workspaces locally
• bootstrap Node 20+ when needed
• install wlfi-agent into a dedicated WLFI_HOME
• auto-install detected Codex / OpenClaw / Claude / generic ~/.agents integrations
• install the Cursor adapter only when the current directory is already a Cursor workspace or WLFI_AGENT_SETUP_CURSOR_WORKSPACE is set
• when no supported AI target is detected, offer the same integrations with all options enabled by default
• finish after installation and hand off wallet creation to a separate wlfi-agent admin setup step by default
• leave relay setup disabled by default so the initial install stays minimal

Prerequisites

• macOS
• network access to download the public installer assets
• Homebrew only when the machine does not already have Node.js 20+

The one-click installer no longer requires local Cargo, pnpm, relay setup, or a preinstalled Node runtime. It still installs Node 20+ locally when the machine does not already have a compatible Node available, because the wlfi-agent launcher runs on Node.

Install from npm

npm i -g @wlfi-agent/cli

npm i -g @wlfi-agent/cli is still the developer-oriented install path. It builds the local Rust runtime during postinstall, so it expects the Rust toolchain and the usual native build prerequisites to already be installed.

Work from this repo

pnpm install
npm run build
npm run install:cli-launcher
npm run install:rust-binaries

On macOS, add export PATH="$HOME/.wlfi_agent/bin:$PATH" to ~/.zshrc, then reload your shell with source ~/.zshrc.

On Linux, add export PATH="$HOME/.wlfi_agent/bin:$PATH" to your shell startup file such as ~/.bashrc, ~/.zshrc, or ~/.profile, then reload that file or open a new shell.

npm run install:cli-launcher installs the wlfi-agent launcher into ~/.wlfi_agent/bin, and npm run install:rust-binaries installs the Rust runtime into the same directory.

Reinstall Rust daemon

If you update Rust daemon code, rerun npm run install:rust-binaries so the root-managed daemon uses the new installed binaries under ~/.wlfi_agent/bin.

Usage

The main user path is:

1. run wlfi-agent admin setup
2. let it install the daemon and set up a wallet
3. use wlfi-agent transfer, wlfi-agent transfer-native, wlfi-agent approve, or wlfi-agent broadcast
4. optionally connect a relay for browser-based manual approvals

User-facing examples below avoid shell env vars on purpose. Prefer prompts, config files, wlfi-agent admin tui, and explicit command flags.

Command model

• wlfi-agent admin setup
  • first-run setup
  • --reuse-existing-wallet reattaches the current local vault when you need to recover the daemon or refresh local credentials without creating a fresh wallet
  • stores the vault password in macOS System Keychain
  • installs the root LaunchDaemon
  • creates a vault key + agent key
  • prints the Ethereum address
• wlfi-agent admin tui
  • token-first policy editor for per-token defaults, destination overrides, and manual approvals
  • when a token or network draft is dirty, Ctrl+S saves that draft and reapplies wallet policies in one step
• wlfi-agent admin reset
  • removes the managed daemon state and local wallet credentials
  • use it only when you are intentionally discarding the current wallet
• wlfi-agent admin uninstall
  • fully removes the managed daemon, root-owned state, local config, local binaries, and logs
  • also removes one-click shell exports plus WLFI AI skill/adaptor installs created by the one-click bootstrap
  • when run from the global npm install, it also removes @wlfi-agent/cli itself
  • use it when you want WLFI removed from the machine instead of preparing for another setup
  • after uninstall, there is no local wallet left on that machine to reuse; use wlfi-agent admin setup --reuse-existing-wallet before uninstalling when you want to keep the current wallet
• wlfi-agent admin ...
  • direct policy and relay configuration commands
• wlfi-agent transfer, wlfi-agent transfer-native, wlfi-agent approve, wlfi-agent broadcast
  • submits signing requests through the daemon
  • uses the configured agent key id plus the macOS Keychain token by default
• wlfi-agent status
  • inspects local wallet security posture, daemon/socket trust, state-file trust, bootstrap artifacts, and agent token storage
  • use --strict when you want CI or automation to fail on warnings
• wlfi-agent repair
  • non-privileged local cleanup for plaintext bootstrap artifacts and legacy agentAuthToken config storage
  • uses --overwrite-keychain only when you have confirmed the plaintext config token is the credential you intend to keep
• wlfi-agent daemon
  • not a user entrypoint; daemon lifecycle is managed by wlfi-agent admin setup

Shared config vs live wallet state

• wlfi-agent admin token set-chain ... and the other wlfi-agent admin chain/token ... editors update the local shared config in ~/.wlfi_agent/config.json. They do not change the live daemon wallet by themselves.
• wlfi-agent config show --json prints that local shared config snapshot. Treat it as your saved source-of-truth draft, not as proof that the current daemon policy attachment already changed.
• Common shared-config commands:
  • add or update a saved network: wlfi-agent admin chain add <key> --chain-id <id> --name <name> --rpc-url <url>
  • remove a saved network profile: wlfi-agent admin chain remove <key>
  • add or update a token on one saved network: wlfi-agent admin token set-chain <tokenKey> <chainKey> --symbol <symbol> --native|--address <token> --decimals <count>
  • remove one token/network mapping without deleting the token everywhere: wlfi-agent admin token remove-chain <tokenKey> <chainKey>
  • remove a configured token entirely: wlfi-agent admin token remove <tokenKey>
• To inspect the concrete contents behind wallet attachedPolicyIds, first read the ids from wlfi-agent config show --json, then query the daemon policies directly with wlfi-agent admin list-policies --policy-id <uuid>.
• To apply shared-config edits to the live wallet, use wlfi-agent admin tui and save the draft there, or rerun wlfi-agent admin setup --reuse-existing-wallet / wlfi-agent-admin bootstrap --from-shared-config.
• wlfi-agent admin wallet-backup export --output ... is the supported backup command and remains available under the admin wallet-backup subcommand tree.

Easiest wallet setup

Run this once:

wlfi-agent admin setup

Preview the exact sanitized setup plan first:

wlfi-agent admin setup --plan

The preview is read-only. It does not prompt for the vault password, does not touch sudo, and does not mutate wallet or policy state. It prints the planned Rust command, trust preflight results, overwrite risk, and the password transport mode that would be used for the real setup.

During a real wlfi-agent admin setup, you may be prompted for two different secrets:

• Vault password: the wallet password you choose for encrypted local state
• macOS admin password for sudo: your macOS login/admin password, used only when setup needs elevated privileges to install or recover the root LaunchDaemon

On a fresh wallet, interactive setup now skips the offline backup wizard by default so the first-run path stays short. If you want a backup during setup, pass --backup-output <path>. Otherwise export one afterward with wlfi-agent admin wallet-backup export --output <path>.

If the local vault already exists and you only need to recover the managed daemon or refresh local setup state, reuse the current wallet instead of creating a fresh one:

wlfi-agent admin setup --reuse-existing-wallet

This reuse path keeps the current vault address, prompts for REUSE in interactive mode, and still requires --yes in non-interactive mode.

Offline wallet backup and restore

After first-run setup, keep an encrypted offline backup of the wallet somewhere separate from the machine itself.

Export a backup:

wlfi-agent admin wallet-backup export --output ~/wlfi-backups/wlfi-wallet-backup.json

Verify the file before you depend on it:

wlfi-agent admin wallet-backup verify ~/wlfi-backups/wlfi-wallet-backup.json

If you are moving to a new machine or recovering after local wallet loss, restore the same wallet with:

wlfi-agent admin setup --restore-wallet-from ~/wlfi-backups/wlfi-wallet-backup.json

That restore flow keeps the wallet address the same, prompts for the backup password locally, and re-establishes the managed daemon plus fresh local agent credentials on the new machine.

After that, the command:

• installs or refreshes the root daemon
• waits for the daemon to come up
• configures the requested spending policies
• imports the agent token into macOS Keychain
• prints the wallet address

By default, setup keeps the freshly issued agent auth token in macOS Keychain and redacts it from CLI output. Only use --print-agent-auth-token when you intentionally need to export that secret.

Example with explicit chain config:

wlfi-agent admin setup \
  --network 11155111 \
  --chain-name sepolia \
  --rpc-url https://rpc.sepolia.example \
  --allow-native-eth \
  --per-tx-max-wei 1000000000000000000 \
  --daily-max-wei 5000000000000000000 \
  --weekly-max-wei 20000000000000000000

Typical output ends with:

setup complete
address: 0x...
vault key id: ...
agent key id: ...
daemon socket: /Library/WLFI/run/daemon.sock
state file: /var/db/wlfi-agent/daemon-state.enc

Policy definition

There are three practical policy layers:

1. default limits for every destination
2. stricter per-destination overrides
3. manual-approval overlays for transactions that should pause for operator review

Token-first policy setup: wlfi-agent admin tui

Use the TUI when you want the easiest way to define:

• a saved token inventory as the primary view
• per-token per-tx / daily / weekly limits in token decimals
• per-token gas / fee / calldata caps
• token-specific destination overrides
• token-specific manual approval overlays
• token mappings across multiple saved networks

Run:

wlfi-agent admin tui

Like admin setup, the TUI stores the new agent auth token in macOS Keychain by default and does not print it unless you pass --print-agent-auth-token.

The TUI starts on the token list, lets you add new tokens or networks, fetches token name/symbol/decimals from the selected network RPC, and bootstraps every saved token across its selected networks.

In the Network Multi-Select field, first save the networks you want in the Networks view, then use ←/→ or h/l (also a/d) to move the focus marker across those saved networks and press Space or Enter to toggle the focused network into the token.

There is no separate "save only" step for dirty token/network drafts in the TUI. Ctrl+S persists the draft and reapplies the wallet together.

Important rule: destination overrides can only tighten the matching token policy; they cannot relax it.

Spend window policies are signing-budget controls, not post-settlement accounting. A request counts against daily/weekly usage once the daemon successfully approves and signs it, including completed manual approvals, even if the signed transaction is broadcast later or ultimately fails on-chain.

Direct setup flags

If you prefer direct flags over the TUI, wlfi-agent admin setup already passes through the common policy and wallet-setup options shown above.

Useful direct flags include:

• --per-tx-max-wei
• --daily-max-wei
• --weekly-max-wei
• --max-gas-per-chain-wei
• --daily-max-tx-count
• --per-tx-max-fee-per-gas-wei
• --per-tx-max-priority-fee-per-gas-wei
• --per-tx-max-calldata-bytes
• --network
• --token
• --allow-native-eth
• --recipient

Manual approval policies

Manual approval is an overlay policy: matching requests are held until an operator approves or rejects them.

Create one with direct flags:

wlfi-agent admin add-manual-approval-policy \
  --network 11155111 \
  --recipient 0x1111111111111111111111111111111111111111 \
  --allow-native-eth \
  --min-amount-wei 1000000000000000 \
  --max-amount-wei 2000000000000000

ERC-20 example:

wlfi-agent admin add-manual-approval-policy \
  --network 11155111 \
  --recipient 0x2222222222222222222222222222222222222222 \
  --token 0x3333333333333333333333333333333333333333 \
  --min-amount-wei 1000000 \
  --max-amount-wei 5000000

The policy matches all transactions of the requested type that fall inside the destination / token / amount range.

Manual approval is still an overlay, not an override. Matching transfers must continue to satisfy every stricter hard limit such as per-tx, daily, weekly, gas, fee, and calldata caps before they can reach the approval flow.

Inspect and resolve manual approvals locally

wlfi-agent admin list-manual-approval-requests

Approve locally:

wlfi-agent admin approve-manual-approval-request \
  --approval-request-id <REQUEST_ID>

Resume an already-approved broadcast-backed request on this machine:

wlfi-agent admin resume-manual-approval-request \
  --approval-request-id <REQUEST_ID>

Reject locally:

wlfi-agent admin reject-manual-approval-request \
  --approval-request-id <REQUEST_ID>

Agent requests

Top-level signing commands always go through the daemon.

After wlfi-agent admin setup, the normal path is to rely on the configured agent key id plus the token already stored in macOS Keychain. You only need --agent-key-id or --agent-auth-token-stdin when overriding that default.

Native transfer:

wlfi-agent transfer-native \
  --network 11155111 \
  --to 0x1111111111111111111111111111111111111111 \
  --amount-wei 1500000000000000

ERC-20 transfer:

wlfi-agent transfer \
  --network 11155111 \
  --token 0x3333333333333333333333333333333333333333 \
  --to 0x2222222222222222222222222222222222222222 \
  --amount-wei 1000000

Approve allowance:

wlfi-agent approve \
  --network 11155111 \
  --token 0x3333333333333333333333333333333333333333 \
  --spender 0x4444444444444444444444444444444444444444 \
  --amount-wei 1000000

Raw policy-checked transaction request:

wlfi-agent broadcast \
  --network 11155111 \
  --to 0x1111111111111111111111111111111111111111 \
  --gas-limit 21000 \
  --max-fee-per-gas-wei 2000000000 \
  --value-wei 1500000000000000

If a request hits a manual-approval policy, the CLI prints:

• approval request id
• frontend approval URL, if relay is configured
• relay URL
• fallback local admin CLI command

Local health checks and cleanup

Inspect the current machine state:

wlfi-agent status

Strict mode is useful in automation:

wlfi-agent status --strict

Repair local non-root issues such as lingering plaintext bootstrap files or legacy agentAuthToken config storage:

wlfi-agent repair

If you intentionally want to keep bootstrap artifacts but redact them in place instead of deleting them:

wlfi-agent repair --redact-bootstrap

Relay setup

Relay is optional. Use it when you want browser-based manual approval.

Local development setup

The one-click installer no longer provisions relay or web services. If you want browser-based manual approval, wire the stack manually with the steps below.

Run the relay and web commands from the repo root, not from apps/relay or apps/web.

0. Install workspace dependencies:

pnpm install

1. Copy the relay config file:

cp apps/relay/.env.example apps/relay/.env

2. Edit apps/relay/.env and set the real values you want to use.

3. Create apps/web/.env.local:

cat > apps/web/.env.local <<'EOF_WEB'
NEXT_PUBLIC_WLFI_RELAY_BASE_URL=http://localhost:8787
NEXT_PUBLIC_WLFI_SITE_NAME=WLFI Approval Console
EOF_WEB

4. Start Valkey:

docker compose -f zarf/docker/valkey/compose.yml up -d

If the relay later fails with connection errors, verify Valkey is actually up:

docker compose -f zarf/docker/valkey/compose.yml ps
docker compose -f zarf/docker/valkey/compose.yml logs --tail=100

5. Start the relay:

pnpm --filter @wlfi-agent/relay dev

6. Start the web UI:

pnpm --filter @wlfi-agent/web exec next dev --hostname 127.0.0.1 --port 3000

7. Point the daemon at the relay and web UI:

wlfi-agent admin set-relay-config \
  --relay-url http://localhost:8787 \
  --frontend-url http://127.0.0.1:3000

The relay does not require daemon auth for daemon registration, polling, or feedback. Only admin relay APIs require RELAY_ADMIN_TOKEN.

8. Confirm the daemon-side relay config:

wlfi-agent admin get-relay-config

Production relay deploy

The relay app includes Serverless configs under zarf/serverless/relay/.

pnpm --filter @wlfi-agent/relay deploy:development
pnpm --filter @wlfi-agent/relay deploy:production

For local dev, prefer the checked-in apps/relay/.env file. For deployed environments, use your normal secret manager or platform config.

Relay approval flow

When relay is configured and a request requires manual approval:

1. the agent CLI prints a frontend approval URL
2. the operator opens that URL in the browser
3. the frontend encrypts the vault password + decision to the daemon’s advertised X25519 public key
4. the relay queues the encrypted update
5. the daemon polls, decrypts, applies the decision, and reports status back
6. for wlfi-agent transfer --broadcast, wlfi-agent transfer-native --broadcast, and wlfi-agent approve --broadcast, the original CLI command keeps waiting on that same approval request and continues automatically after approval
7. if that original broadcast command has already exited after the request was approved, operators can recover the same approved request locally with wlfi-agent admin resume-manual-approval-request --approval-request-id <UUID>
8. commands outside those broadcast flows still print the approval details and exit, so operators can approve or reject the request separately

If the frontend link is unavailable, operators can always fall back to the local admin CLI approval command printed by the agent CLI.

For the auto-waiting broadcast flows above:

• do not rerun the original command after approving in the browser
• the CLI polls every 2 seconds for up to 5 minutes
• if the daemon returns a different approval request id while waiting, the CLI stops and tells you to inspect the approval status before rerunning
• approval details and waiting events go to stderr; the final successful --json result still goes to stdout
• if the original command is already gone but the request is still Approved, use wlfi-agent admin resume-manual-approval-request --approval-request-id <UUID> instead of rebuilding the transaction by hand

Operational notes

• The daemon state file lives at /var/db/wlfi-agent/daemon-state.enc and is intended to be root-only.
• The managed socket lives at /Library/WLFI/run/daemon.sock.
• If setup says the daemon password does not unlock the stored state, use the original vault password or reset the managed state before setting up a fresh wallet.
• If the machine is lost or the local wallet is gone, restore from your encrypted offline backup with wlfi-agent admin setup --restore-wallet-from <backup.json>.
• Forgotten vault password recovery is still destructive if you do not have a valid offline backup: run wlfi-agent admin reset, then wlfi-agent admin setup to create a new wallet.
• After changing daemon-side Rust code, run npm run install:rust-binaries and restart the managed daemon through wlfi-agent admin setup.

Reset a forgotten password

If you forgot the vault password and do not have a valid offline backup, there is no recovery path for the existing encrypted daemon state. Use reset only when you intentionally want to discard the old wallet and create a new wallet.

If you do have a wallet backup, do not reset. Use:

wlfi-agent admin setup --restore-wallet-from <backup.json>

wlfi-agent admin reset

For automation or CI-style local flows:

wlfi-agent admin reset --yes

By default, reset keeps non-secret config like chain settings, but removes the managed daemon state, the daemon password stored in System Keychain, the local agent token, and lingering bootstrap artifacts.

If you want a totally clean local slate too:

wlfi-agent admin reset --yes --delete-config

After reset, run wlfi-agent admin setup to create a new wallet.

Fully uninstall WLFI Agent

Use uninstall when you want a full local cleanup instead of preparing for another setup. It removes:

• the managed LaunchDaemon
• /Library/WLFI
• /var/db/wlfi-agent
• /var/log/wlfi-agent
• ~/.wlfi_agent
• the daemon password in System Keychain
• the local agent auth token in Keychain

wlfi-agent admin uninstall removes the managed daemon and local WLFI files on that machine. When the command itself is running from the global npm install of @wlfi-agent/cli, it also removes that global package, so wlfi-agent disappears after the command exits. If you are running from a repo checkout or another non-global path, the managed state is still removed but the current CLI checkout is left alone.

wlfi-agent admin uninstall

For automation or CI-style local flows:

wlfi-agent admin uninstall --yes

Useful commands

wlfi-agent admin setup
wlfi-agent admin tui
wlfi-agent admin uninstall
wlfi-agent admin get-relay-config
wlfi-agent admin list-manual-approval-requests
wlfi-agent admin resume-manual-approval-request --approval-request-id <UUID>
wlfi-agent wallet
npm run install:rust-binaries
pnpm build
pnpm typecheck