Skip to main content
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

brew install node@20

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.
Anchor is required for building and deploying the escrow program.Verify installation:
anchor --version
See Anchor documentation for troubleshooting.

​
Installation Steps

1

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
2

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.
3

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:
  1. Syncs the program ID from the deploy keypair
  2. Builds the Anchor program
  3. 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:
ServicePortDescription
API Gateway3000Main entry point for all requests
Wallet Engine3002Wallet creation, signing, balances
Policy Engine3003Policy evaluation and approval gates
Agent Runtime4004Agent lifecycle and autonomous execution
Protocol Adapters3005Protocol-specific transaction builders
Transaction Engine3006Transaction pipeline and confirmation
Audit & Observability3007Audit events and metrics
MCP Server3008MCP-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

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.
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
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
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).

Build docs developers (and LLMs) love

Get started for freeTalk to us