Installation

This guide covers all installation options for Starknet Agentic, from the platform-aware CLI to manual repository setup.

System Requirements

Requirement	Minimum	Recommended
Node.js	18.0+	20.0+ (LTS)
pnpm	9.0+	10.0+
Disk Space	500 MB	1 GB
OS	macOS, Linux, Windows	macOS, Linux

Installation Methods

Method 1: Platform-Aware CLI (Recommended)

The create-starknet-agent CLI auto-detects your environment and configures Starknet accordingly.

npx create-starknet-agent@latest

The CLI detects and configures for:

Platform	Detection	Configuration
OpenClaw / MoltBook	`OPENCLAW_HOME` env or `~/.openclaw/`	MCP config + skills + secrets
Claude Code	`CLAUDE_CODE` env or `.claude/`	`.mcp.json` + CLAUDE.md
Cursor	`CURSOR_SESSION_ID` env	Cursor MCP settings
Daydreams	`DAYDREAMS_HOME` env	MCP integration
Generic MCP	`mcp.json` present	MCP server config
Standalone	No platform detected	Full agent project scaffold

CLI Commands

# Main setup (auto-detect platform)
npx create-starknet-agent@latest

# Configure wallet credentials
npx create-starknet-agent credentials

# Verify setup is working
npx create-starknet-agent verify

# Force specific platform
npx create-starknet-agent@latest --platform claude-code

# Non-interactive (for agent self-setup)
npx create-starknet-agent@latest --non-interactive --json

# Show detected platform
npx create-starknet-agent@latest --detect-only

CLI Options

Option	Description
`--platform <name>`	Force platform: `openclaw`, `claude-code`, `cursor`, `daydreams`, `generic-mcp`, `standalone`
`--skills <list>`	Comma-separated skills: `starknet-wallet,starknet-defi`
`--network <name>`	Network: `mainnet`, `sepolia`
`--non-interactive`	Skip all prompts (for agent self-setup)
`--json`	Output machine-readable JSON
`--detect-only`	Show detected platform and exit
`--from-env`	Import credentials from environment variables
`--yes`, `-y`	Accept defaults

Agent Self-Setup

Agents can configure themselves in non-interactive mode:

npx create-starknet-agent@latest --non-interactive --json

Returns:

{
  "success": true,
  "platform": "openclaw",
  "configured": {
    "mcp": "~/.openclaw/mcp/starknet.json",
    "skills": ["starknet-wallet", "starknet-defi"]
  },
  "pendingSetup": {
    "credentials": ["STARKNET_PRIVATE_KEY", "STARKNET_ACCOUNT_ADDRESS"]
  },
  "nextSteps": [
    "Add credentials to ~/.openclaw/secrets/starknet/",
    "Restart agent to load new MCP server"
  ]
}

Method 2: Clone Full Repository

Best for exploring examples, contributing, or manual MCP server setup.

Clone the repository

git clone https://github.com/keep-starknet-strange/starknet-agentic.git
cd starknet-agentic

Install dependencies

pnpm install

This installs dependencies for all packages in the monorepo.

Build all packages

pnpm build

Verify installation

pnpm test

All tests should pass.

Method 3: Install Individual Packages

Best for using Starknet Agentic in your own project.

MCP Server

For AI assistant integration:

npm install @starknet-agentic/mcp-server

A2A Adapter

For agent-to-agent communication:

npm install @starknet-agentic/a2a

Individual npm packages will be available after the v1.0 release. For now, use the CLI or monorepo installation method.

Method 4: Use as Git Submodule

For embedding in larger projects:

git submodule add https://github.com/keep-starknet-strange/starknet-agentic.git lib/starknet-agentic
cd lib/starknet-agentic
pnpm install && pnpm build

Package Structure

After installation, you'll have access to these packages:

starknet-agentic/
|-- packages/
|   |-- create-starknet-agent/   # Platform-aware CLI tool
|   |   |-- src/
|   |   |   |-- index.ts         # Main CLI entry point
|   |   |   |-- platform.ts      # Platform detection
|   |   |   |-- credentials.ts   # Secure credential setup
|   |   |   |-- verify.ts        # Health check commands
|   |   |   +-- wizards.ts       # Platform-specific setup wizards
|   |   +-- package.json
|   |
|   |-- starknet-mcp-server/     # MCP tools for AI agents (14 tools)
|   |   |-- src/                 # Source code
|   |   |-- dist/                # Built output (after pnpm build)
|   |   +-- package.json
|   |
|   |-- starknet-a2a/            # Agent-to-Agent protocol
|   |   |-- src/
|   |   +-- package.json
|   |
|   |-- starknet-agent-passport/ # Capability metadata client
|   |
|   +-- x402-starknet/           # X-402 payment protocol
|
|-- contracts/
|   |-- erc8004-cairo/           # ERC-8004 Cairo contracts
|   |   |-- src/                 # Contract source (identity, reputation, validation)
|   |   |-- tests/               # Unit tests (178+ tests)
|   |   +-- Scarb.toml           # Cairo package config
|   |
|   |-- agent-account/           # Agent Account contract (110 tests)
|   |
|   +-- huginn-registry/         # Thought provenance registry
|
|-- skills/                      # Reusable agent skills
|   |-- starknet-wallet/
|   |-- starknet-defi/
|   |-- starknet-identity/
|   |-- starknet-mini-pay/
|   |-- starknet-anonymous-wallet/
|   |-- cairo-contracts/         # Cairo contract patterns
|   |-- cairo-testing/           # snforge testing patterns
|   |-- cairo-security/          # Security patterns from 50+ audits
|   |-- cairo-optimization/      # Gas optimization rules
|   +-- cairo-deploy/            # Deployment with sncast
|
+-- examples/                    # Example implementations
    |-- hello-agent/             # Minimal E2E proof
    |-- defi-agent/              # Arbitrage bot example
    |-- onboard-agent/           # Agent deployment with gasfree
    +-- controller-calls/        # Cartridge Controller integration

Installing Cairo Contracts (Optional)

If you want to work with the ERC-8004 Cairo contracts:

Prerequisites

Scarb 2.14.0+
Starknet Foundry 0.54.1+

Recommended: Install via asdf

The recommended way to install Scarb and Starknet Foundry is through asdf, which makes version management easy:

# Add plugins
asdf plugin add scarb
asdf plugin add starknet-foundry

# Install and set versions
asdf install scarb 2.14.0
asdf install starknet-foundry 0.54.1
asdf set --home scarb 2.14.0
asdf set --home starknet-foundry 0.54.1

See the Scarb asdf guide and Starknet Foundry asdf guide for more details.

Installation

# Install Scarb
curl --proto '=https' --tlsv1.2 -sSf https://docs.swmansion.com/scarb/install.sh | sh

# Install Starknet Foundry
curl -L https://raw.githubusercontent.com/foundry-rs/starknet-foundry/master/scripts/install.sh | sh
snfoundryup

Build and Test Contracts

cd contracts/erc8004-cairo

# Build contracts
scarb build

# Run unit tests (178+ tests)
snforge test

# Run specific test
snforge test --filter test_register_agent

Verifying Installation

CLI Verification

npx create-starknet-agent verify

Checks:

MCP server configuration exists
Required credentials are set
Skills are installed
Can query Starknet (optional)

Manual Verification

# Check Node.js version
node --version  # Should be 18+

# Check pnpm version
pnpm --version  # Should be 9+

# Verify packages built correctly
ls packages/starknet-mcp-server/dist/
# Should see: index.js, index.d.ts, etc.

# Run unit tests
pnpm test

# Check Cairo installation (optional)
scarb --version  # Should be 2.14.0+
snforge --version  # Should be 0.54.1+

Common Installation Issues

Development Setup

For contributing or modifying Starknet Agentic:

Install Development Dependencies

# Install with dev dependencies
pnpm install

# Set up git hooks (optional, for contributors)
pnpm prepare

Run in Watch Mode

# Watch and rebuild on changes
pnpm dev

# Or for a specific package
cd packages/starknet-mcp-server
pnpm dev

Linting and Formatting

# Lint all packages
pnpm lint

# Format code
pnpm format

Next Steps

After installation:

Quick Start - Configure and test your setup
Configuration - Environment variables reference
MCP Server Guide - Connect to Claude or other AI assistants