CLI and local daemon

This page covers machine-side installation of the AgentPay SDK runtime.

After completing these steps:

• agentpay should be on your path

• built-in chain and token defaults should be available

• the machine should be ready for wallet setup

Requirements

The one-click installer only requires macOS and network access (plus Homebrew when Node.js 20+ is not already present). It downloads a prebuilt runtime bundle and handles everything else.

For installing from source:

• macOS or Linux

• Node.js 20+

• pnpm

• Rust 1.87.0+ (rustup recommended)

• Xcode Command Line Tools on macOS (xcode-select --install)

pnpm run install:cli-launcher installs the agentpay launcher into ~/.agentpay/bin, and pnpm run install:rust-binaries installs the Rust runtime into the same directory.

One-click install

The fastest path:

curl -fsSL https://wlfi.sh | bash

To install the latest version explicitly, or pin a specific release:

# latest
curl -fsSL https://wlfi.sh/latest | bash

# specific version
curl -fsSL https://wlfi.sh/0.1.0 | bash

The script downloads a prebuilt macOS runtime bundle, installs agentpay into a dedicated AGENTPAY_HOME, and auto-detects supported AI host integrations. After install, run agentpay admin setup to create a wallet.

Install from source

Clone the SDK repository and build:

git clone https://github.com/worldliberty/agentpay-sdk.git
cd agentpay-sdk
pnpm install
pnpm run build
pnpm run install:cli-launcher
pnpm run install:rust-binaries

The install:cli-launcher step installs the agentpay launcher to ~/.agentpay/bin. Add it to your shell path:

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

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

If you change Rust daemon code, rerun:

pnpm run install:rust-binaries

That refreshes the binaries used by the managed local daemon installation.

What install does and does not do

Installing the CLI gives you the command surface. The wallet runtime is established later by agentpay admin setup.

agentpay admin setup is the supported entrypoint for:

• storing the vault password securely

• installing or refreshing the managed local daemon

• creating or reusing wallet access

• importing agent auth material into macOS Keychain

Because setup installs a root-managed LaunchDaemon, it can require local machine authorization during the setup flow.

Do not run agentpay daemon directly. Daemon lifecycle is managed through agentpay admin setup.

Built-in defaults

The SDK seeds built-in defaults so the first run is usable immediately. See Built-in defaults in the overview for the full list of chains and tokens.

Managed runtime defaults:

• daemon socket -> /Library/AgentPay/run/daemon.sock

• state file -> /var/db/agentpay/daemon-state.enc

• launchd label -> com.agentpay.daemon

Most commands accept a --daemon-socket <path> flag to override the socket path. You can also set the AGENTPAY_DAEMON_SOCKET environment variable as a persistent override.

Update to a new SDK version

When a new version of the SDK is released, update the CLI and refresh the local Rust binaries.

If you used the one-click installer, rerun the one-click install script.

If you installed from source:

git pull
pnpm install
pnpm run build
pnpm run install:cli-launcher
pnpm run install:rust-binaries

After updating, rerun setup to refresh the managed local daemon:

agentpay admin setup

The existing wallet, policy, and config are preserved across updates. Only the daemon binary and CLI surface are refreshed.

Override a chain profile when needed

If you need to save a different RPC or chain profile, do it explicitly. For example:

agentpay admin chain switch bsc --rpc-url https://bsc.drpc.org --save --json

You can inspect the current config at any time with:

agentpay config show --json

Sanity checks

Run these once after installation:

agentpay --version
agentpay --help

If both commands succeed, the installation is in place and the next step is Wallet setup.

Security model

The SDK includes several defense-in-depth measures:

• Admin brute-force protection - 5 failed attempts trigger a 30-second lockout

• File system trust model - ownership checks, symlink prevention, and permission enforcement on managed paths

• Constant-time comparison for all auth token validation

• Secret zeroization throughout the Rust codebase after use

• Input size limits - 16 KB max for stdin/keychain secret inputs, 256 KB max for config files

• Atomic file writes with fsync for crash consistency

• #![forbid(unsafe_code)] on core Rust crates

IPC transport security

The daemon communicates with the CLI over Unix domain sockets. Transport-level controls include:

• Symlink rejection - both the socket path and its parent directory must not be symlinks

• Root ownership - the daemon socket must be owned by root (uid 0)

• Socket permissions - set to 0o600 (root-only) for restricted peers

• Peer EUID verification - every incoming connection is checked against separate admin and agent allowlists; unauthorized peers are rejected

• Per-RPC access levels - admin RPCs (setup, policy, reset) are restricted to admin-allowed EUIDs; agent RPCs (sign, transfer) use a separate allowlist

With the CLI installed and verified, continue to Wallet setup.