Installation

This guide covers installing Agentic Wallet for local development, testing, and production deployment.

Prerequisites

Node.js

Version: >= 20.x

node --version

npm

Version: >= 10.x

npm --version

Solana CLI

Version: >= 1.18.xRequired for devnet funding and program deployment

solana --version

Anchor CLI

Version: >= 0.31.xRequired for escrow program build/deploy

anchor --version

Installing Prerequisites

Install Node.js and npm

macOS (Homebrew)
Linux (nvm)
Windows (nvm-windows)

brew install node@20

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 20
nvm use 20

Download from nvm-windows releases, then:

nvm install 20
nvm use 20

Install Solana CLI

sh -c "$(curl -sSfL https://release.solana.com/stable/install)"

Add to your PATH:

export PATH="$HOME/.local/share/solana/install/active_release/bin:$PATH"

Verify installation:

solana --version

Configure for devnet:

solana config set --url devnet

See Solana CLI documentation for more details.

Install Anchor CLI

Anchor is required for building and deploying the escrow program.

Using avm (recommended)
From source

Install Anchor Version Manager:

cargo install --git https://github.com/coral-xyz/anchor avm --locked --force

Install Anchor:

avm install 0.31.0
avm use 0.31.0

cargo install --git https://github.com/coral-xyz/anchor --tag v0.31.0 anchor-cli --locked

Verify installation:

anchor --version

See Anchor documentation for troubleshooting.

Installation Steps

Clone or Download Repository

If you have the repository locally, navigate to it:

cd /path/to/agentic-wallet

Or clone from your source:

git clone <your-repository-url>
cd agentic-wallet

Install Dependencies

Install all workspace dependencies:

npm install

This installs dependencies for:

2 applications (apps/*): API Gateway, CLI
7 services (services/*): wallet-engine, policy-engine, agent-runtime, protocol-adapters, transaction-engine, audit-observability, mcp-server
3 packages (packages/*): common, sdk, observability

The post-install script runs automatically to patch RPC WebSocket compatibility.

Verify Installation

Run quality gates to ensure everything is installed correctly:

npm run typecheck
npm run lint
npm run test
npm run build

All commands should complete successfully.

If npm run build fails, check that all dependencies installed correctly and that you have sufficient disk space.

Post-Installation

Build All Packages

Build all services and packages:

npm run build

This compiles TypeScript for:

All 7 microservices
SDK and shared packages
CLI application

Build Escrow Program (Optional)

If you plan to use escrow functionality, build the Anchor program:

npm run escrow:build

This command:

Syncs the program ID from the deploy keypair
Builds the Anchor program
Generates IDL and type definitions

You only need to build the escrow program if you plan to deploy it or modify escrow functionality.

Verification

System Health Check

Run the doctor command to verify your installation:

npm run cli -- doctor

Expected output:

✓ Node.js version: 20.x.x
✓ npm version: 10.x.x
✓ Solana CLI: 1.18.x
✓ Anchor CLI: 0.31.x
✓ All services built
✓ Environment configured

Service Startup Test

Verify all services can start:

# Load environment
set -a; source .env.example; set +a

# Start services
npm run dev

You should see 8 services listening:

[gateway] API Gateway listening on port 3000
[wallet] Wallet Engine listening on port 3002
[policy] Policy Engine listening on port 3003
[agent] Agent Runtime listening on port 3004
[protocol] Protocol Adapters listening on port 3005
[tx] Transaction Engine listening on port 3006
[audit] Audit & Observability listening on port 3007
[mcp] MCP Server listening on port 3008

Press Ctrl+C to stop services.

Repository Structure

After installation, your repository should have this structure:

agentic-wallet/
├── apps/
│   ├── api-gateway/          # REST API gateway
│   └── cli/                  # Command-line interface
├── services/
│   ├── wallet-engine/        # Wallet custody & signing
│   ├── policy-engine/        # Policy evaluation
│   ├── agent-runtime/        # Agent lifecycle & execution
│   ├── protocol-adapters/    # Protocol integrations
│   ├── transaction-engine/   # Transaction pipeline
│   ├── audit-observability/  # Audit logs & metrics
│   └── mcp-server/           # MCP tools interface
├── packages/
│   ├── common/               # Shared types & schemas
│   ├── sdk/                  # TypeScript SDK
│   └── observability/        # Observability utilities
├── programs/
│   └── escrow/               # Anchor escrow program
├── scripts/
│   ├── intent-runner.ts      # Intent execution script
│   ├── wallets.ts            # Wallet management script
│   ├── devnet-smoke.ts       # Smoke tests
│   └── ...                   # Other utility scripts
├── docs/                     # Documentation
├── .env.example              # Example environment config
├── package.json              # Root package manifest
└── README.md                 # Project overview

Service Ports

After installation, these ports will be used by default:

Service	Port	Description
API Gateway	3000	Main entry point for all requests
Wallet Engine	3002	Wallet creation, signing, balances
Policy Engine	3003	Policy evaluation and approval gates
Agent Runtime	4004	Agent lifecycle and autonomous execution
Protocol Adapters	3005	Protocol-specific transaction builders
Transaction Engine	3006	Transaction pipeline and confirmation
Audit & Observability	3007	Audit events and metrics
MCP Server	3008	MCP-compatible tool endpoints

All ports are configurable via environment variables. See the Configuration guide.

Data Directories

By default, services store data in their local directories:

services/wallet-engine/data/          # Encrypted wallet keys
services/policy-engine/data/          # Policy definitions
services/agent-runtime/data/          # Agent state
services/transaction-engine/data/     # Transaction history
services/audit-observability/data/    # Audit logs & metrics

Production deployments should:

Use dedicated data directories outside the source tree
Implement regular backups of wallet-engine data
Use KMS/HSM for key storage instead of encrypted files
Configure external databases (PostgreSQL) instead of SQLite

Next Steps

Quickstart

Create your first wallet and execute a transaction

Configuration

Configure environment variables and signer backends

Creating Wallets

Learn wallet creation and management

Deployment

Deploy to production with proper security

Troubleshooting

npm install fails with EACCES error

You may have permission issues. Try:

sudo chown -R $(whoami) ~/.npm
npm install

Or use a Node version manager like nvm to avoid permission issues.

anchor build fails with 'cargo not found'

You need Rust installed for Anchor:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source $HOME/.cargo/env

Then retry:

npm run escrow:build

TypeScript compilation errors

Ensure you’re using the correct Node version:

node --version  # Should be >= 20

Clean and rebuild:

rm -rf node_modules package-lock.json
rm -rf apps/*/node_modules services/*/node_modules packages/*/node_modules
npm install
npm run build

Port already in use errors

Check for existing processes:

lsof -ti tcp:3000,3002,3003,3004,3005,3006,3007,3008

Kill them:

PIDS=$(for p in 3000 3002 3003 3004 3005 3006 3007 3008; do lsof -ti tcp:$p; done | sort -u)
[ -n "$PIDS" ] && kill $PIDS

Or configure different ports in .env (see Configuration).

Getting Started

Architecture

Core Concepts

Operations

Security

Integration

Prerequisites

Node.js

npm

Solana CLI

Anchor CLI

Installing Prerequisites

Installation Steps

Post-Installation

Build All Packages

Build Escrow Program (Optional)

Verification

System Health Check

Service Startup Test

Repository Structure

Service Ports

Data Directories

Next Steps

Quickstart

Configuration

Creating Wallets

Deployment

Troubleshooting

​Prerequisites

Node.js

npm

Solana CLI

Anchor CLI

​Installing Prerequisites

​Installation Steps

​Post-Installation

​Build All Packages

​Build Escrow Program (Optional)

​Verification

​System Health Check

​Service Startup Test

​Repository Structure

​Service Ports

​Data Directories

​Next Steps

Quickstart

Configuration

Creating Wallets

Deployment

​Troubleshooting

Prerequisites

Installing Prerequisites

Installation Steps

Post-Installation

Build All Packages

Build Escrow Program (Optional)

Verification

System Health Check

Service Startup Test

Repository Structure

Service Ports

Data Directories

Next Steps

Troubleshooting