PerkOS CLI

Scaffold-style templates for building Web3 apps with AI agent backends.

Templates

| Template | Description | Chain | |----------|-------------|-------| | 🔐 selfclaw | Human verification with Self.xyz proofs | EVM (Foundry) | | 🏆 talent | Builder Score reputation gating | EVM (Foundry) | | ⚡ stacks | Clarity smart contracts on Stacks | Stacks (Clarinet) |

Each template includes:

• Smart contracts with tests
• Next.js frontend
• Docker + OpenClaw AI backend
• Local blockchain & faucet
• VPS deployment scripts

Workshop

Interactive exercises for the ERC-8004 Workshop. Run against the live PerkOS Stack at stack.perkos.xyz.

# Run all 7 exercises
npx @perkos/cli workshop all

# Run a specific exercise
npx @perkos/cli workshop 1

| Exercise | Description | |----------|-------------| | 1 | Discovery — Query 5 standard agent endpoints | | 2 | Identity — Lookup on-chain identity on Base | | 3 | Reputation — Query agent reputation score | | 4 | Onboarding — Get full agent registration package | | 5 | x402 Payment — Explore payment networks and health | | 6 | Full Flow — End-to-end agent lifecycle | | 7 | Live Registration — Register an agent on Base mainnet (requires wallet) |

Exercise 7: Live Agent Registration

Exercise 7 performs real on-chain transactions on Base mainnet. It registers your wallet as an agent in the ERC-8004 Identity Registry.

Setup:

# Copy the example env file
cp .env.example .env

# Add your private key (wallet needs ~$0.01 ETH on Base for gas)
# Edit .env and set PERKOS_PRIVATE_KEY=0x...

Run:

npx @perkos/cli workshop 7

What it does:

1. Reads your wallet from .env
2. Calls PerkOS Stack for onboarding package
3. Checks if already registered on-chain
4. Signs and submits register() to Base mainnet
5. Waits for confirmation and shows BaseScan link
6. Verifies registration + queries reputation

Quick Start

Prerequisites

# Node.js 18+
node --version

# For EVM templates (selfclaw, talent)
curl -L https://foundry.paradigm.xyz | bash
foundryup

# For Stacks template
brew install clarinet

# Docker (for OpenClaw backend)
docker --version

Create a Project

# Clone the repo
git clone https://github.com/PerkOS-xyz/PerkOS-Client.git
cd PerkOS-Client

# Install CLI dependencies
npm install

# Build CLI
npm run build

# Create a new project
node dist/cli.js create-app my-app --template selfclaw

Local Testing

Test SelfClaw Template (EVM)

# 1. Create project
node dist/cli.js create-app test-selfclaw --template selfclaw

# 2. Go to project
cd test-selfclaw

# 3. Initialize git (required for Foundry)
git init

# 4. Install Foundry dependencies
cd contracts
forge install foundry-rs/forge-std OpenZeppelin/openzeppelin-contracts --no-git

# 5. Build contracts
forge build

# 6. Run tests
forge test -vvv
# Expected: 5 tests passing

# 7. Start local chain (Terminal 1)
anvil --block-time 2

# 8. Deploy contracts (Terminal 2)
forge script script/Deploy.s.sol --rpc-url http://localhost:8545 --broadcast --private-key 0xac0974bec39a17e36ba4a6b4d238ff944bacb478cbed5efcae784d7bf4f2ff80

# 9. Start frontend (Terminal 3)
cd ../frontend
pnpm install
pnpm dev
# Open http://localhost:3000

Test Talent Template (EVM)

# 1. Create project
node dist/cli.js create-app test-talent --template talent

# 2. Go to project
cd test-talent
git init

# 3. Install & test
cd contracts
forge install foundry-rs/forge-std OpenZeppelin/openzeppelin-contracts --no-git
forge build
forge test -vvv
# Expected: 8 tests passing

# 4. Run full stack (same as selfclaw)

Test Stacks Template

# 1. Create project
node dist/cli.js create-app test-stacks --template stacks

# 2. Go to project
cd test-stacks/contracts

# 3. Check contracts
clarinet check
# Expected: 2 contracts checked, warnings only

# 4. Install test dependencies
npm install

# 5. Run tests
npm test
# Expected: 7 tests passing

# 6. Start devnet
clarinet devnet start

# 7. Start frontend (new terminal)
cd ../frontend
pnpm install
pnpm dev

Test OpenClaw Docker Backend

# In any project directory
cd docker

# Copy env file
cp .env.example .env

# Add your API key
echo "ANTHROPIC_API_KEY=sk-ant-your-key" >> .env

# Start OpenClaw
docker compose up -d

# Check logs
docker compose logs -f

# Test health endpoint
curl http://localhost:3030/health

# Stop
docker compose down

All-in-One Commands

Once inside a project, use these convenience commands:

# Install everything
pnpm install:all

# Run full stack (chain + contracts + frontend + openclaw)
pnpm dev

# Individual services
pnpm chain          # Start local blockchain
pnpm deploy         # Deploy contracts
pnpm frontend       # Start frontend
pnpm openclaw:start # Start OpenClaw Docker

# Testing
pnpm test           # Run contract tests

# Production
pnpm build          # Build frontend
pnpm openclaw:deploy # Deploy OpenClaw to VPS

Project Structure

my-app/
├── contracts/          # Smart contracts
│   ├── src/            # Contract source
│   ├── script/         # Deploy scripts
│   └── test/           # Tests
├── frontend/           # Next.js app
│   └── src/
│       ├── app/
│       ├── components/
│       └── lib/
├── docker/             # OpenClaw backend
│   ├── Dockerfile
│   ├── docker-compose.yml
│   └── config.yaml
├── scripts/            # Utilities
│   ├── faucet.mjs      # Local faucet
│   └── deploy-vps.sh   # VPS deployment
└── package.json

Templates Detail

🔐 SelfClaw

Human verification for AI agents using Self.xyz passport proofs.

• Contract: SelfClawVerifier.sol - On-chain verification attestations
• Features: EIP-712 signatures, expiration, revocation
• Use Case: Prove an agent is controlled by a verified human

🏆 Talent

Gate access based on Talent Protocol Builder Score.

• Contract: BuilderScoreGate.sol - Score-based access control
• Features: Score thresholds, attestations, tiers
• Use Case: Premium features for established builders

⚡ Stacks

Clarity smart contracts on the Stacks blockchain.

• Contracts: counter.clar, nft-collection.clar
• Features: SIP-009 NFT, minting, Bitcoin settlement
• Use Case: Bitcoin-secured applications

VPS Deployment

Deploy OpenClaw to any VPS via SSH:

# Configure in docker/.env
VPS_HOST=your-server.com
VPS_USER=root
VPS_SSH_KEY=~/.ssh/id_rsa
VPS_DEPLOY_PATH=/opt/openclaw

# Deploy
pnpm openclaw:deploy

Development

# Clone
git clone https://github.com/PerkOS-xyz/PerkOS-Client.git
cd PerkOS-Client

# Install
npm install

# Build
npm run build

# Test CLI
node dist/cli.js templates

# Run TypeScript directly
npx tsx src/cli.ts create-app test --template selfclaw

License

MIT

Built with 💖 by PerkOS