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=6702
DATABASE_URL=postgres://user:password@localhost:5432/spawnclaw
SPAWN_AGENT_URL=http://localhost:4000
SPAWN_AGENT_SECRET=your-shared-secret
OPENROUTER_API_KEY=sk-or-v1-xxx
INSTANCE_COST_USD=15

Create spawn-agent/.env:

SPAWNCLAW_SECRET=your-shared-secret
PORT=4000
GATEWAY_PORT_START=18790
GATEWAY_PORT_END=18850

4. Initialize Database

cd apps/api
npx drizzle-kit push

5. Start Services

# Terminal 1: Spawn Agent
cd spawn-agent && node index.js

# Terminal 2: API
cd 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)

Run setup script on Ubuntu 22.04/24.04
Clone repo to /opt/spawnclaw
Build Docker runtime image
Configure environment variables
Initialize database
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:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.agents		.agents
apps		apps
docker-runtime		docker-runtime
docs		docs
packages		packages
scripts		scripts
spawn-agent		spawn-agent
.gitattributes		.gitattributes
.gitignore		.gitignore
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
spawnclaw-api.env		spawnclaw-api.env
spawnclaw-spawn-agent.env		spawnclaw-spawn-agent.env
steps.md		steps.md
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

SpawnClaw

Features

Architecture

Tech Stack

Quick Start

Prerequisites

1. Clone & Install

2. Build Docker Runtime Image

3. Configure Environment

4. Initialize Database

5. Start Services

Project Structure

API Endpoints

Public

Authenticated (Bearer: wallet address)

Admin (Bearer: ADMIN_SECRET)

Multi-VPS Deployment

Production Deployment

Backend (VPS)

Frontend (Vercel)

Environment Variables

Control Plane API (apps/api/.env)

Spawn Agent (spawn-agent/.env)

Development

Server Capacity Guidelines

Contributing

License

Support

Acknowledgments

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Control Plane API (`apps/api/.env`)

Spawn Agent (`spawn-agent/.env`)

Packages