# 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:

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

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

```bash
# 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:

```bash
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:

```bash
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](/agentpay-sdk/overview.md#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:

```bash
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:

```bash
agentpay admin setup --reuse-existing-wallet
```

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:

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

You can inspect the current config at any time with:

```bash
agentpay config show --json
```

## Sanity checks

Run these once after installation:

```bash
agentpay --version
agentpay --help
```

If both commands succeed, the installation is in place and the next step is [Wallet setup](/agentpay-sdk/workflows/wallet-setup.md).

## 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](/agentpay-sdk/workflows/wallet-setup.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.worldlibertyfinancial.com/agentpay-sdk/install/cli-and-daemon-install.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.