claw-spawn

Complete Digital Ocean VPS provisioning and OpenClaw bot orchestration service.

This repo supports:

• Standalone microservice (claw-spawn-server)
• Embedding into a larger Axum server via claw_spawn::server::router(...)

🚀 Super Quick Start (One Command)

Just run make and you're ready to go:

# Clone the repository
git clone https://github.com/conorholds/claw-spawn.git
cd claw-spawn

# Run everything (creates .env, sets up DB, runs migrations, builds, and starts server)
make

That's it! The server will start on http://localhost:8080

Then edit .env and add your DigitalOcean API token:

# Edit the .env file
CLAW_DIGITALOCEAN_TOKEN=your_actual_token_here

📋 Makefile Commands

The Makefile provides easy commands for development:

🔧 Manual Setup (If You Prefer)

Prerequisites

• Rust/Cargo: https://rustup.rs/
• PostgreSQL: brew install postgresql (macOS) or apt-get install postgresql
• sqlx-cli: cargo install sqlx-cli

1. Set Environment Variables

export CLAW_DATABASE_URL="postgres://user:password@localhost/claw_spawn"
export CLAW_DIGITALOCEAN_TOKEN="your_digitalocean_api_token"
export CLAW_ENCRYPTION_KEY="$(openssl rand -base64 32)"

2. Setup Database

# Create database
createdb claw_spawn

# Run migrations
sqlx migrate run

3. Build and Run

# Build release binary
cargo build --release --bin claw-spawn-server

# Start server
./target/release/claw-spawn-server

🐳 Docker Quick Start

# Start with Docker Compose (includes PostgreSQL)
make docker-run

# Or manually:
docker-compose up --build

The Docker setup includes:

• PostgreSQL database (auto-created)
• Automatic migrations on startup
• Server exposed on port 8080

📦 Environment Variables

🪂 Droplet Bootstrap Notes

• The droplet must be able to reach CLAW_CONTROL_PLANE_URL over HTTPS. If you run claw-spawn locally, you typically need a tunnel (ngrok/cloudflared) until you have a live URL.
• Workspace customization (janebot-cli) runs once and writes:
  • Marker: /opt/openclaw/.customizer_ran
  • Status: /opt/openclaw/customizer_status.txt

🧩 Embedded Usage (Integrate Into Larger Axum Server)

claw-spawn supports a dual architecture:

• Standalone microservice via the claw-spawn-server binary
• Embedded router via claw_spawn::server::router(...)

Example (host app nests this service under /spawn):

use axum::Router;
use claw_spawn::infrastructure::AppConfig;
use claw_spawn::server::{build_state_with_pool, router};
use sqlx::PgPool;

let cfg = AppConfig::from_env()?;
let pool = PgPool::connect(&cfg.database_url).await?;
let state = build_state_with_pool(cfg, pool, /* run_migrations */ true).await?;

let app = Router::new().nest("/spawn", router(state));

📦 Crate Usage

Add to Cargo.toml:

[dependencies]
# Core library only (no Axum server/router)
claw-spawn = { version = "0.1", default-features = false }

Or, if you want the embeddable HTTP server/router:

[dependencies]
claw-spawn = { version = "0.1", features = ["server"] }

🎯 API Usage Examples

Create a Bot

curl -X POST http://localhost:8080/bots \
  -H "Content-Type: application/json" \
  -d '{
    "account_id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "My First Bot",
    "persona": "beginner",
    "asset_focus": "majors",
    "algorithm": "trend",
    "strictness": "medium",
    "paper_mode": true,
    "max_position_size_pct": 10.0,
    "max_daily_loss_pct": 5.0,
    "max_drawdown_pct": 15.0,
    "max_trades_per_day": 20,
    "llm_provider": "openai",
    "llm_api_key": "sk-your-openai-key-here"
  }'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "account_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "My First Bot",
  "persona": "beginner",
  "status": "provisioning",
  "droplet_id": 123456789,
  "created_at": "2024-01-15T10:30:00Z"
}

Check Bot Status

curl http://localhost:8080/bots/{bot_id}

Bot Actions

# Pause
curl -X POST http://localhost:8080/bots/{bot_id}/actions -d '{"action": "pause"}'

# Resume  
curl -X POST http://localhost:8080/bots/{bot_id}/actions -d '{"action": "resume"}'

# Destroy
curl -X POST http://localhost:8080/bots/{bot_id}/actions -d '{"action": "destroy"}'

📚 API Endpoints

App Endpoints

• POST /bots - Create bot
• GET /bots/:id - Get bot details
• GET /accounts/:id/bots - List account bots
• POST /bots/:id/actions - pause/resume/redeploy/destroy

Bot Agent Endpoints

• GET /bot/:id/config - Pull config
• POST /bot/:id/config_ack - Acknowledge config
• POST /bot/:id/heartbeat - Health check
• POST /bot/register - Initial registration

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                       claw-spawn                            │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Axum HTTP Server                          │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐│  │
│  │  │  App API     │  │  Bot API     │  │  Health      ││  │
│  │  │  (/bots/*)   │  │  (/bot/*)    │  │  (/health)   ││  │
│  │  └──────────────┘  └──────────────┘  └──────────────┘│  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Application Layer                       │  │
│  │  ┌──────────────┐  ┌──────────────┐                  │  │
│  │  │Provisioning │  │   BotLifecycle              │  │
│  │  │   Service    │  │   Service                     │  │
│  │  └──────────────┘  └──────────────┘                  │  │
│  └──────────────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────────────┐  │
│  │              Infrastructure Layer                    │  │
│  │  ┌──────────────┐  ┌──────────────┐  ┌────────────┐│  │
│  │  │DigitalOcean │  │PostgreSQL    │  │  Crypto    ││  │
│  │  │   Client     │  │Repositories  │  │(AES-256)   ││  │
│  │  └──────────────┘  └──────────────┘  └────────────┘│  │
│  └──────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                  ┌───────────────────────┐
                  │   DigitalOcean VPS    │
                  │  ┌─────────────────┐  │
                  │  │  OpenClaw Bot   │  │
                  │  │   Agent         │  │
                  │  └─────────────────┘  │
                  └───────────────────────┘

🔐 Security

• AES-256-GCM encryption for all secrets (LLM API keys)
• Per-bot registration tokens for authentication
• Firewall rules on droplets (default deny inbound)
• No secrets in logs - all sensitive data redacted

📖 Documentation

• Setup: See Super Quick Start and Manual Setup
• API Reference: See API Usage Examples
• Architecture: See Architecture section

🛠️ Development

# Quick dev cycle
make dev

# Run tests
make test

# Check code
make check

# Format code
make fmt

# Lint
make lint

📝 Database Migrations

# Create migration
make migrate-add

# Run migrations
make migrate

# Check status
make migrate-status

# Revert last
make migrate-revert

🧹 Troubleshooting

"sqlx-cli not found"

make install-sqlx

"Database connection failed"

# Check PostgreSQL is running
make db

"Port 8080 already in use"

# Edit .env and change CLAW_SERVER_PORT
CLAW_SERVER_PORT=8081 make run

🤝 Library Usage

Use as a library in your Rust project:

use claw_spawn::{
    application::{ProvisioningService, BotLifecycleService},
    domain::{Account, BotConfig, Persona, SubscriptionTier},
    infrastructure::{AppConfig, DigitalOceanClient, PostgresAccountRepository},
};

// See README.md for full example

📄 License

MIT