SpawnClaw

Open-source platform for deploying isolated AI agent instances in Docker containers with wallet-based authentication and usage billing.

SpawnClaw lets users spawn isolated AI agent instances (powered by OpenClaw) inside Docker containers. Users authenticate via MetaMask wallet, deposit tokens for USD-based balance, then create instances connected to Telegram or WhatsApp.

Features

• Wallet Authentication - MetaMask/Solana wallet login with JWT tokens
• Docker Isolation - Each AI agent runs in its own isolated container
• Multi-chain Deposits - Accept deposits on Base and Solana networks
• OpenRouter Integration - Access Claude, GPT, Llama, Gemini via single API
• Multi-VPS Scaling - Distribute instances across multiple servers
• Telegram/WhatsApp Support - Connect agents to messaging platforms
• Real-time Dashboard - Monitor instances, deposits, and usage

Architecture

Frontend (Next.js) → Control Plane API → Spawn Agent → Docker Containers (OpenClaw)

Component	Port	Description
apps/web	6700	Landing page with wallet connect
apps/admin	6703	Admin dashboard
apps/api	6702	Control Plane API (auth, billing, orchestration)
spawn-agent	4000	Docker container lifecycle manager
docker-runtime	-	Dockerfile + scripts for OpenClaw containers
Gateway Range	18790-18850	One port per OpenClaw instance

Tech Stack

• Frontend: Next.js 16, React 19, Tailwind CSS, Dynamic.xyz
• Backend: Express.js, PostgreSQL, Drizzle ORM
• Infrastructure: Docker, PM2
• AI: OpenRouter API
• Blockchain: Base, Solana (viem, @solana/web3.js)

Quick Start

Prerequisites

• Node.js 22+
• pnpm 9.0+
• Docker (or Colima on macOS)
• PostgreSQL database
• OpenRouter API key(s)

1. Clone & Install

git clone https://github.com/jsonpreet/spawnclaw.git
cd spawnclaw
pnpm install

2. Build Docker Runtime Image

cd docker-runtime
docker build -t spawnclaw-runtime .

3. Configure Environment

Create apps/api/.env:

PORT=6702DATABASE_URL=postgres://user:password@localhost:5432/spawnclawSPAWN_AGENT_URL=http://localhost:4000SPAWN_AGENT_SECRET=your-shared-secretOPENROUTER_API_KEY=sk-or-v1-xxxINSTANCE_COST_USD=15

Create spawn-agent/.env:

SPAWNCLAW_SECRET=your-shared-secretPORT=4000GATEWAY_PORT_START=18790GATEWAY_PORT_END=18850

4. Initialize Database

cd apps/api
npx drizzle-kit push

5. Start Services

# Terminal 1: Spawn Agentcd spawn-agent && node index.js
# Terminal 2: APIcd apps/api && node index.js
# Terminal 3: Web App
pnpm dev:web

Visit http://localhost:6700 to get started.

Project Structure

spawnclaw/
├── apps/
│ ├── web/ # Landing page (Next.js)
│ ├── admin/ # Admin dashboard (Next.js)
│ └── api/ # Control Plane API (Express)
├── spawn-agent/ # Docker lifecycle manager
├── docker-runtime/ # OpenClaw container image
├── packages/
│ ├── ui/ # Shared UI components
│ ├── lib/ # Shared utilities
│ ├── types/ # TypeScript types
│ └── config/ # Shared configurations
├── docs/ # Documentation
└── scripts/ # Deployment scripts

API Endpoints

Public

Method	Endpoint	Description
GET	/health	System health check
GET	/api/treasury	Treasury wallet addresses
GET	/api/pricing	Token price & instance cost

Authenticated (Bearer: wallet address)

Method	Endpoint	Description
GET	/api/balance	User's USD balance
POST	/api/deposits/verify	Verify token deposit
POST	/api/instances/create	Create new instance
GET	/api/instances	List user's instances
POST	/api/instances/:id/stop	Stop an instance

Admin (Bearer: ADMIN_SECRET)

Method	Endpoint	Description
PATCH	/api/admin/users/:id/block	Block/unblock user
GET	/api/compute/providers	List compute providers
GET	/api/compute/capacity	Pool capacity info

Multi-VPS Deployment

SpawnClaw supports distributing instances across multiple VPS servers:

Frontend → Control Plane API (1 server)
↓
ComputePool (scheduler)
↙ ↓ ↘
VPS-1 VPS-2 VPS-3
(spawn-agent) (spawn-agent) (spawn-agent)

Configure in apps/api/.env:

DOCKER_PROVIDERS='[ { "id": "vps-us-1", "url": "http://167.71.0.1:4000", "secret": "shared-secret", "maxInstances": 8, "priority": 10 }, { "id": "vps-eu-1", "url": "http://138.68.0.1:4000", "secret": "shared-secret", "maxInstances": 8, "priority": 5 }]'SCHEDULER_STRATEGY=priority_first

Production Deployment

Backend (VPS)

1. Run setup script on Ubuntu 22.04/24.04
2. Clone repo to /opt/spawnclaw
3. Build Docker runtime image
4. Configure environment variables
5. Initialize database
6. Start services with PM2

cd /opt/spawnclaw/spawn-agent && pm2 start index.js --name spawn-agent
cd /opt/spawnclaw/apps/api && pm2 start index.js --name spawnclaw-api
pm2 save && pm2 startup

Frontend (Vercel)

Deploy apps/web and apps/admin to Vercel:

cd apps/web && vercel --prod
cd apps/admin && vercel --prod

Set environment variables in Vercel dashboard:

• NEXT_PUBLIC_API_URL - Your API URL
• NEXT_PUBLIC_DYNAMIC_ENVIRONMENT_ID - Dynamic.xyz ID

Environment Variables

Control Plane API (apps/api/.env)

Variable	Required	Default	Description
PORT	No	6702	API server port
DATABASE_URL	Yes	-	PostgreSQL connection string
SPAWN_AGENT_URL	No	http://localhost:4000	Spawn agent URL
SPAWN_AGENT_SECRET	Yes	-	Shared secret
OPENROUTER_API_KEY	Yes	-	OpenRouter API key
INSTANCE_COST_USD	No	15	Cost per instance
INSTANCE_MEMORY	No	1g	RAM per container
TREASURY_BASE	No	-	Base treasury address
TOKEN_ADDRESS_BASE	No	-	Token contract address

Spawn Agent (spawn-agent/.env)

Variable	Required	Default	Description
SPAWNCLAW_SECRET	Yes	-	Shared secret
PORT	No	4000	Agent port
GATEWAY_PORT_START	No	18790	First gateway port
GATEWAY_PORT_END	No	18850	Last gateway port

Development

# Install dependencies
pnpm install
# Start all services in dev mode
pnpm dev
# Start specific app
pnpm dev:web
pnpm dev:api
# Build all apps
pnpm build
# Lint code
pnpm lint

Server Capacity Guidelines

For a VPS with 12GB RAM / 6 CPU cores:

Metric	Value
RAM per instance (peak)	~800MB
RAM per instance (steady)	~300MB
Recommended instances	6-8
Max instances	~10

Key constraint: RAM, not ports. Each instance needs ~1GB allocated.

Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• Documentation: See /docs folder for detailed guides
• Issues: https://github.com/jsonpreet/spawnclaw/issues
• Discussions: https://github.com/jsonpreet/spawnclaw/discussions

Acknowledgments

• OpenClaw - The AI agent framework
• OpenRouter - AI model API gateway
• Dynamic.xyz - Wallet authentication

---

Built with ❤️ by the SpawnClaw team