pi-harness

Pi-Harness ⚡

"Standing on the shoulders of giants — pi-coding-agent by Mario Zechner is the real hero here. We're just building the saddle."

Pi-Harness is the top-level harness for the Pi ecosystem. It takes the extraordinary power of pi-coding-agent — Mario Zechner's thoughtful, fast, and capable coding agent — and wraps it as a headless HTTP/SSE server that fits into your workflow, not the other way around.

Unlike generic platforms that force companies to adapt to their opinions, Pi-Harness is designed to be deeply customizable. Configure your own models, tools, system prompts, extensions, and skills. Run it on a $5 VPS, a Kubernetes cluster, or even your phone via Termux. One process serves many users. Inference happens in the cloud. Your hardware just needs Node.js.

🚀 Standalone & Headless	No TUI, no database, no auth complexity. Just a clean HTTP API over pi-coding-agent's core SDK.
🏢 Company-First Design	Your workflow, your rules. Custom system prompts, tool allowlists, extensions, and skills per-deployment.
📡 Real-Time SSE Streaming	Every thought, tool call, and token streams to clients via Server-Sent Events. Build reactive UIs.
🔧 Full Pi Ecosystem Support	Not just coding agent — designed to harness all Pi packages: pi-ai, pi-agent-core, pi-tui, pi-lens, and more.
🧩 Extension & Skill Registry	Official skills and extensions published via git. Drop them in and they work. Community-driven ecosystem.
📱 Runs Anywhere	Linux, macOS, WSL2, Docker, Kubernetes, Termux on Android. Minimal resource footprint.

🙏 With Gratitude

Pi-Harness would not exist without pi-coding-agent by Mario Zechner. The Pi ecosystem — pi-ai, pi-agent-core, pi-coding-agent, pi-tui, pi-lens — represents some of the most thoughtful agent infrastructure built for developers. Mario's work on session management, the tool loop, the event system, and the TUI is the foundation everything here rests on.

We are building this with his blessing and with deep respect. Pi-Harness is not a fork, not a replacement, and not a competitor. It is a deployment layer — a way to run Pi's incredible agent logic in contexts where the interactive TUI isn't the right fit: background services, multi-user servers, embedded devices, automated pipelines, and company-specific integrations.

If you haven't tried pi-coding-agent directly, you should. It's beautiful.

npm install -g @mariozechner/pi-coding-agent
pi                            # experience the TUI firsthand

⚡ Quick Start

Install (Recommended)

npm install -g @openzosma/pi-harness

Requires Node.js 22+. That's it — no cloning, no monorepo, no pnpm.

First Run

pi-harness

On first run, pi-harness detects you're not configured and walks you through an interactive setup wizard. It asks for your LLM provider, API key, model preferences, and server settings. Your config is saved to ~/.pi-harness/.env.

After setup, the server starts automatically.

Daily Usage

pi-harness                  # Start server (foreground)
pi-harness start --daemon   # Start in background
pi-harness status           # Check if running
pi-harness logs             # Tail server logs
pi-harness stop             # Stop background daemon
pi-harness tui              # Connect with interactive client
pi-harness setup            # Re-run setup wizard
pi-harness --help           # Show all commands

One-Liner Install (Alternative)

Prefer curl? We got you:

curl -fsSL https://raw.githubusercontent.com/zosmaai/openzosma/main/packages/pi-harness/scripts/install.sh | bash

This installs Node.js (if needed), pnpm, clones the repo, builds everything, and adds pi-harness to your PATH.

Manual Setup (OpenZosma Monorepo)

For development within the openzosma repo:

cd /path/to/openzosma
pnpm install
pnpm --filter @openzosma/pi-harness build
pnpm --filter @openzosma/pi-harness start

📖 What Is Pi-Harness?

Pi-coding-agent has three run modes:

• Interactive mode — The TUI (pi command). Beautiful, immersive, local.
• Print mode — Single-shot CLI output.
• SDK mode — Programmatic via AgentSession, createAgentSession().

Pi-Harness uses SDK mode. The TUI (pi-tui) is never loaded. The core agent logic runs headlessly, streaming events through an async generator that the HTTP server consumes and forwards as SSE.

This means:

• No GPU required locally — inference happens at your chosen API endpoint
• Multiple sessions, one process — concurrent users share a lightweight Node.js runtime
• Any client — web dashboard, mobile app, CLI, Discord bot, CI pipeline
• Tiny footprint — ~50-100 MB base + ~10-30 MB per session

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Your Client                              │
│  (Web dashboard / CLI / Mobile / Discord / CI)              │
└──────────────────────┬──────────────────────────────────────┘
                       │ HTTP + SSE
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                     Pi-Harness (Node.js)                     │
│                                                              │
│  ┌─────────────┐    ┌─────────────────────────────────────┐ │
│  │ Hono HTTP   │───▶│  HarnessSessionManager              │ │
│  │ Server      │    │  • Multi-session in-process         │ │
│  │ :8080       │◀───│  • Per-session workspace isolation  │ │
│  └─────────────┘    └─────────────────────────────────────┘ │
│         │                              │                     │
│         │                              ▼                     │
│         │                    ┌──────────────────┐            │
│         │                    │ @openzosma/agents │            │
│         │                    │ (PiAgentProvider) │            │
│         │                    └────────┬─────────┘            │
│         │                             │                      │
│         ▼                             ▼                      │
│   REST + SSE                    @mariozechner/               │
│   /sessions                     pi-coding-agent              │
│   /sessions/:id/messages       (headless SDK mode)           │
│                                NO TUI — core only            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    Cloud LLM APIs (OpenRouter, OpenAI,
                    Anthropic, OpenCode Go, Ollama, etc.)

🔌 API Reference

Session Management

Method	Path	Description
GET	/health	Health check + uptime + session count
POST	/sessions	Create a new session
GET	/sessions	List active session IDs
GET	/sessions/:id	Get session metadata
DELETE	/sessions/:id	End a session

Messaging

Method	Path	Description
POST	/sessions/:id/messages	Send message → SSE stream
POST	/sessions/:id/steer	Steering message mid-turn
POST	/sessions/:id/followup	Queue follow-up after turn
POST	/sessions/:id/cancel	Cancel active turn

Create Session

curl -X POST http://localhost:8080/sessions \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-secret" \
  -d '{
    "model": "claude-sonnet-4",
    "systemPromptPrefix": "You are a senior Rust engineer.",
    "toolsEnabled": ["read", "bash", "write"]
  }'

Response:

{ "sessionId": "abc-123-..." }

Send Message (SSE)

curl -N -X POST http://localhost:8080/sessions/abc-123/messages \
  -H "Content-Type: application/json" \
  -H "x-api-key: dev-secret" \
  -d '{"content": "Write a hello world in Rust"}'

Response (SSE stream):

event: turn_start
data: {"type":"turn_start","id":"..."}

event: message_start
data: {"type":"message_start","id":"..."}

event: message_update
data: {"type":"message_update","id":"...","text":"I'll"}

event: message_update
data: {"type":"message_update","id":"...","text":" create"}

event: tool_call_start
data: {"type":"tool_call_start","toolCallId":"...","toolName":"write","toolArgs":"{...}"}

event: tool_call_end
data: {"type":"tool_call_end","toolCallId":"...","toolName":"write","toolResult":"File written."}

event: turn_end
data: {"type":"turn_end","id":"..."}

⚙️ Configuration

All configuration is via environment variables. No config files, no database, no ceremony.

Required

Variable	Description	Example
OPENROUTER_API_KEY	OpenRouter API key	sk-or-v1-...
OPENAI_API_KEY	OpenAI API key	sk-...
ANTHROPIC_API_KEY	Anthropic API key	sk-ant-...
OPENZOSMA_LOCAL_MODEL_URL	Custom OpenAI-compatible endpoint	https://opencode.ai/zen/go/v1

You only need one provider key. Pi-Harness auto-detects which one you have.

Server Settings

Variable	Default	Description
PI_HARNESS_PORT	8080	HTTP server port
PI_HARNESS_HOST	0.0.0.0	Host to bind to
PI_HARNESS_API_KEY	(none)	Require x-api-key header
PI_HARNESS_MAX_SESSIONS	0 (unlimited)	Max concurrent sessions
PI_HARNESS_IDLE_TIMEOUT_MINUTES	30	Auto-cleanup idle sessions
PI_HARNESS_WORKSPACE	./workspace	Session workspace root
PI_HARNESS_MAX_BODY_SIZE	10MB	Request body limit

Agent Defaults

Variable	Description	Example
PI_HARNESS_PROVIDER	Default LLM provider	openrouter, anthropic, openai
PI_HARNESS_MODEL	Default model ID	claude-sonnet-4, gpt-4o
PI_HARNESS_TOOLS	Default tools (comma-separated)	read,bash,write,edit
PI_HARNESS_SYSTEM_PROMPT_PREFIX	Prefix for all sessions	"You work at Acme Corp..."
PI_HARNESS_SYSTEM_PROMPT_SUFFIX	Suffix for all sessions	"Always write tests."
PI_HARNESS_EXTENSIONS_DIR	Load pi-coding-agent extensions	/path/to/extensions
PI_HARNESS_SKILLS_DIR	(future) Load skills from directory	/path/to/skills
PI_HARNESS_VERBOSE	false	Enable verbose logging

Full Example

# Provider: OpenCode Go (affordable bundled models)
export OPENZOSMA_LOCAL_MODEL_URL="https://opencode.ai/zen/go/v1"
export OPENZOSMA_LOCAL_MODEL_API_KEY="sk-..."
export OPENZOSMA_LOCAL_MODEL_ID="qwen3.6-plus"

# Server
export PI_HARNESS_PORT=8080
export PI_HARNESS_API_KEY="company-secret"
export PI_HARNESS_MAX_SESSIONS=50
export PI_HARNESS_IDLE_TIMEOUT_MINUTES=30

# Agent defaults for your company
export PI_HARNESS_PROVIDER="local"
export PI_HARNESS_MODEL="qwen3.6-plus"
export PI_HARNESS_TOOLS="read,bash,write,edit,grep,find,ls"
export PI_HARNESS_SYSTEM_PROMPT_PREFIX="You are a senior engineer at Acme Corp. Follow our style guide at https://acme.dev/style. Use TypeScript, prefer functional patterns, and always write tests."
export PI_HARNESS_EXTENSIONS_DIR="/opt/pi-harness/extensions"

# Run
pnpm --filter @openzosma/pi-harness start

🖥️ Running in Background

Built-in Daemon (Easiest)

Pi-Harness has native daemon support — no external tools needed:

pi-harness start --daemon   # Start in background
pi-harness status             # Check if running
pi-harness logs               # Tail server logs
pi-harness stop               # Stop daemon

Your config and logs live in ~/.pi-harness/.

systemd (Linux Servers)

Create /etc/systemd/system/pi-harness.service:

[Unit]
Description=Pi-Harness Agent Server
After=network.target

[Service]
Type=simple
User=pi-harness
WorkingDirectory=/opt/pi-harness
EnvironmentFile=/opt/pi-harness/.env
ExecStart=/usr/bin/pi-harness start
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

sudo systemctl daemon-reload
sudo systemctl enable pi-harness
sudo systemctl start pi-harness
sudo systemctl status pi-harness

pm2 (Node.js Process Manager)

npm install -g pm2

pm2 start "pi-harness start" --name pi-harness

pm2 save
pm2 startup

# Logs
pm2 logs pi-harness

# Restart
pm2 restart pi-harness

Docker Compose

services:
  pi-harness:
    build: ./packages/pi-harness
    ports:
      - "8080:8080"
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - PI_HARNESS_API_KEY=${PI_HARNESS_API_KEY}
      - PI_HARNESS_MAX_SESSIONS=50
      - PI_HARNESS_SYSTEM_PROMPT_PREFIX=${PI_HARNESS_SYSTEM_PROMPT_PREFIX}
    volumes:
      - ./workspace:/app/workspace
      - ./extensions:/app/extensions
    restart: unless-stopped

Kubernetes

apiVersion: apps/v1
kind: Deployment
metadata:
  name: pi-harness
spec:
  replicas: 2
  selector:
    matchLabels:
      app: pi-harness
  template:
    metadata:
      labels:
        app: pi-harness
    spec:
      containers:
        - name: pi-harness
          image: openzosma/pi-harness:latest
          ports:
            - containerPort: 8080
          env:
            - name: OPENROUTER_API_KEY
              valueFrom:
                secretKeyRef:
                  name: llm-secrets
                  key: openrouter
            - name: PI_HARNESS_API_KEY
              valueFrom:
                secretKeyRef:
                  name: harness-secrets
                  key: api-key
            - name: PI_HARNESS_MAX_SESSIONS
              value: "100"
          resources:
            requests:
              memory: "256Mi"
              cpu: "250m"
            limits:
              memory: "1Gi"
              cpu: "1000m"

🧩 Extensions & Skills

Pi-Coding-Agent Extensions

Pi-coding-agent supports extensions loaded from a directory. Pi-Harness exposes this via PI_HARNESS_EXTENSIONS_DIR.

Extensions are JavaScript/TypeScript modules that hook into the agent lifecycle. They can add tools, modify prompts, or react to events. Place them in the extensions directory and they'll be loaded automatically on session creation.

export PI_HARNESS_EXTENSIONS_DIR="/opt/pi-harness/extensions"

Directory structure:

extensions/
├── my-company-tool/
│   ├── package.json
│   └── index.js          # exports extension hooks
└── custom-validator/
    └── index.js

Skills (Coming Soon)

Skills are higher-level procedural memory — reusable task patterns the agent can invoke by name. Think of them as functions the LLM can call that encode multi-step workflows.

We're building an official skills registry at github.com/zosmaai/pi-harness-skills. Drop a skill directory into PI_HARNESS_SKILLS_DIR and the agent gains new capabilities:

skills/
├── deploy-to-vercel/
│   ├── skill.json          # metadata, parameters, description
│   └── workflow.md         # step-by-step instructions for the agent
├── run-security-audit/
│   ├── skill.json
│   └── workflow.md
└── generate-changelog/
    ├── skill.json
    └── workflow.md

Skills follow the open AgentSkills standard where possible.

🌐 Ecosystem Vision

Pi-Harness is not just a coding agent server. It is the top-level harness for the entire Pi ecosystem.

What This Means

Package	What It Does	How Pi-Harness Uses It
pi-coding-agent	The core coding agent with tools and session management	Primary engine — runs headlessly via SDK mode
pi-ai	LLM abstraction layer	Model routing — supports any provider via pi-ai's registry
pi-agent-core	Agent loop, event system, tool framework	Event streaming — SSE events originate from pi-agent-core
pi-tui	Terminal UI framework	Client option — TUI client can be built on pi-tui components
pi-lens	Code intelligence and navigation	Future — LSP-powered code context for agent sessions

Our Philosophy

Big tech platforms make you fit into their workflow. They decide which models you can use, which tools are available, how auth works, and how much it costs. They own your data and your configuration.

Pi-Harness makes the platform fit into your workflow. You choose:

• Which LLM provider (or your own endpoint)
• Which tools are enabled per-deployment
• What the agent knows about your company
• Where it runs and who has access
• How it integrates with your existing systems

This is infrastructure as code for AI agents. Deploy it, configure it, extend it. It's yours.

📊 Resource Usage

Pi-Harness is designed to run on minimal hardware:

Component	Usage
Node.js runtime	~50-100 MB base
Per-session overhead	~10-30 MB (depends on history)
50 concurrent sessions	~1-2 GB RAM total
CPU between turns	Near zero
CPU during streaming	Spikes during LLM I/O and tool execution

No GPU required. All inference happens at your configured API endpoint.

🔗 Comparison

	Pi-Harness	Gateway + Orchestrator	sandbox-server
Weight	Light	Heavy	Medium
Database	None	PostgreSQL + Better Auth	None
Auth	Optional API key	Full user auth	None
Sandbox	No	Yes (OpenShell)	Yes (OpenShell)
Dashboard	No	Yes (Next.js)	No
A2A Protocol	No	Yes	No
Multi-tenancy	Sessions	Users + Orgs	Sessions
Best For	Standalone agent server	Full platform	Sandboxed agents

Use Pi-Harness when you want a simple, deployable agent server without platform complexity.

Use Gateway when you need user auth, billing, persistent history, and a web dashboard.

🛠️ Development

git clone https://github.com/zosmaai/openzosma.git
cd openzosma
pnpm install
pnpm --filter @openzosma/pi-harness build
pnpm --filter @openzosma/pi-harness check    # TypeScript check
pnpm --filter @openzosma/pi-harness dev      # tsx watch mode

Project Structure

packages/pi-harness/
├── src/
│   ├── cli.ts             # CLI router (lightweight, no heavy deps)
│   ├── commands.ts        # Heavy command implementations (start, tui)
│   ├── index.ts           # Server entry point (daemon/foreground)
│   ├── server.ts          # Hono HTTP server (REST + SSE)
│   ├── session-manager.ts # Multi-session lifecycle manager
│   ├── config.ts          # Environment configuration
│   ├── types.ts           # Shared TypeScript types
│   └── tui.ts             # Terminal client
├── scripts/
│   ├── install.sh         # One-liner installer
│   ├── setup.sh           # Interactive setup wizard
│   └── build-bundle.mjs   # esbuild bundler for standalone npm
├── dist/                  # Bundled + compiled output
├── README.md
└── package.json

🗺️ Roadmap

• Headless HTTP/SSE server
• Multi-session management
• TUI client (pi-harness-tui)
• One-liner install script
• Interactive setup wizard
• Default tools, prompts, and extensions
• Session persistence (SQLite/JSON) for restart survival
• WebSocket transport option
• gRPC server mode
• Metrics endpoint (Prometheus)
• Official skills registry (git-based)
• Extension marketplace
• A2A protocol endpoint
• Horizontal pod autoscaling example
• Termux/Android automated install
• pi-lens integration for code intelligence

🤝 Contributing

We welcome contributions! This is an open-source project by Zosma AI, built with deep respect for the Pi ecosystem.

• 🐛 Open an issue
• 💡 Start a discussion
• 🔀 Submit a PR

Special thanks to Mario Zechner for creating the Pi ecosystem and for his blessing in building this harness.

📜 License

MIT — see the OpenZosma LICENSE.

The underlying pi-coding-agent and Pi packages are licensed under their respective licenses (MIT). All credit for the agent intelligence belongs to Mario Zechner and the Pi contributors.

Built with 💜 by Zosma AI
_{Standing on the shoulders of Mario Zechner's Pi ecosystem}