@spfunctions/harness

Dual pi-agent runtime harness. Two agents (local + Cloudflare) negotiate, share state, and self-modify via a 5-message protocol. Open source. $1–2/day to run.

npm i -g @spfunctions/harness

After install, the binary is sparkco.

Quick Start

sparkco init

The setup wizard will:

1. Check your environment (git, node, wrangler)
2. Configure Cloudflare credentials
3. Deploy the server runtime
4. Configure LLM models for both agents
5. Optionally install pi/Claude Code skill

Prerequisites

• Node.js >= 18
• git
• wrangler (npm install -g wrangler)
• pi (optional) (npm install -g @anthropic-ai/claude-code)

Cloudflare Setup

You need a Cloudflare API Token with these permissions:

Permission	Level	Why
Workers Scripts	Edit	Deploy/update Workers
Workers KV Storage	Edit	Create/read/write KV
Workers Routes	Edit	Configure routing
Durable Objects	Edit	Create DO namespace
Account Settings	Read	Verify account

Create your token:

1. Go to https://dash.cloudflare.com/profile/api-tokens
2. Click "Create Token"
3. Choose "Create Custom Token"
4. Add the permissions listed above
5. Zone Resources: All zones (or specific zone)
6. Click "Continue to summary" then "Create Token"
7. Copy the token — you'll need it during sparkco init

Agent Model Configuration

SparkCo Harness runs two pi-agent runtimes that need LLM access to autonomously write code and modify environments.

During Setup

The setup wizard will ask you to configure an LLM provider. Recommended: OpenRouter — one key accesses all models.

Default model: minimax/minimax-m2.7 ($0.30/$1.20 per M tokens). Best cost-performance ratio for continuous agent operation.

Environment Variables (non-interactive mode)

Variable	Required	Default
SPARKCO_LLM_PROVIDER	No	openrouter
SPARKCO_LLM_API_KEY	Yes	—
SPARKCO_CLIENT_MODEL	No	minimax/minimax-m2.7
SPARKCO_SERVER_MODEL	No	Same as client

After Setup

sparkco model              # View current config
sparkco model test         # Verify both agents can respond
sparkco model set both anthropic/claude-sonnet-4-6  # Switch models
sparkco model key set <new-key>                      # Update API key

Costs

At default settings (MiniMax M2.7), continuous operation costs roughly $1-2/day depending on activity level. This covers both client and server pi runtimes.

Commands

Command	Description
sparkco init	Interactive setup wizard
sparkco status	System overview
sparkco daemon start|stop|restart	Manage client daemon
sparkco send <type> <content>	Send protocol message
sparkco inbox	View pending requests
sparkco routes list|add|remove	Manage local endpoints
sparkco ps	Process management
sparkco manifest show|history|rollback	Version control
sparkco logs [name]	View logs
sparkco deploy	Deploy/redeploy server
sparkco secret set|list|delete	Manage secrets
sparkco model show|set|list|key|test	Manage LLM models
sparkco server status|logs|tasks	Server runtime management
sparkco improve status|issues|fixes|pause|resume	Self-improvement engine
sparkco destroy	Tear down everything

All commands support --json for machine-readable output (useful for pi).

Architecture

CLIENT (local)              CLOUDFLARE            SERVER (VPS)
+--------------+     +------------------+     +--------------+
| pi-agent     |     | Worker (relay)   |     | pi-agent     |
| daemon       |<SSE>| ├─ auth         |<SSE>| daemon       |
| read/write   | REST| ├─ SSE relay    | REST| read/write   |
| npm/git      |---->| └─ KV/R2 proxy  |<----| npm/git      |
+--------------+     | Durable Object   |     | scheduler    |
                     | └─ event log     |     +--------------+
                     +------------------+

The communication protocol has 5 message types:

• capability-request — "I need you to have X capability"
• capability-ready — "X is ready at endpoint Y"
• data — Payload on an established channel
• state-sync — Heartbeat + version + process status
• negotiate — Free-form discussion about capabilities

Pi Integration

After init, install the sparkco skill:

# For pi
cp src/pi/skill.md ~/.pi/agent/skills/sparkco/SKILL.md

# For Claude Code
cp src/pi/skill.md ~/.claude/skills/sparkco/SKILL.md

Or let the setup wizard handle it automatically.

Pi can then use all sparkco commands via bash to coordinate client-server workflows autonomously.

Configuration

Config lives at ~/.sparkco/config.json. See sparkco status for current values.

Development

npm install
npm test                    # all tests
npm run test:unit           # unit tests only
npm run test:integration    # integration tests only
npx tsx scripts/dev.ts      # local dev server + daemon

Uninstall

sparkco destroy
npm uninstall -g @spfunctions/harness

License

Apache-2.0