runpiper Documentation

Welcome to the runpiper documentation! Here you’ll find comprehensive guides and references to help you build, deploy, and run LLM tasks in production.

What is runpiper?

runpiper is a Rust-based API server and CLI for defining, running, and managing LLM tasks. The codebase focuses on task definitions, authenticated API access, and a runtime that executes prompt templates against supported model providers.

Why developers use runpiper

  • Repeatable LLM workflows: versioned task definitions make prompts auditable and easy to promote.
  • Unified runtime + API: one service handles task execution, chat completions, and model routing.
  • Operational control: track runs, capture usage, and manage access with API keys and auth.
  • Built-in integrations: web search and web fetch are exposed as first-class API tools.
  • CLI-first workflow: ship and test tasks from the command line without building custom tooling.

Built in the code today

  • Task registry and versions: Create, list, activate, and delete task definitions stored in Postgres.
  • Task execution: Run tasks synchronously or asynchronously with callback delivery, plus run status tracking.
  • Chat completions gateway: /v1/chat/completions with streaming support for supported providers.
  • Model catalog and providers: Anthropic plus OpenAI-compatible providers (OpenAI, Cerebras, xAI) with a baked-in model list.
  • Auth and access control: Magic-link login, invite redemption, and API key management.
  • Built-in tools: Web search via Brave and web fetch via Jina Reader APIs.
  • Wallet accounting: Balance and transaction history, plus an admin top-up endpoint.
  • CLI workflow: rp commands for login, tasks, keys, invites, wallet, models, and running the server.

Concrete usage examples

Create a task definition in TOML (used by rp task push):

[task]
name = "summarize"
description = "Summarize input text"

[constraints]
max_cost = 0.01
max_response_time = "30s"

[prompts]
user = "Summarize this text: {{input}}"

[input]
input = { type = "string", required = true }

[output]
format = "text"

Push, deploy, and test it from the CLI:

rp task push summarize.task.toml
rp task deploy summarize
rp task test summarize -i '{"input":"Runpiper makes tasks repeatable."}'

Run the task directly over HTTP using an API key:

curl -X POST "https://<endpoint>/v1/run/summarize" \
  -H "Authorization: Bearer rp_<api_key>" \
  -H "Content-Type: application/json" \
  -d '{"input":"Runpiper makes tasks repeatable."}'

Quick Start

New to runpiper? Get started in under 60 seconds:

Quick Start Guide →

Core Concepts

Learn the three main building blocks of runpiper:

  • Tasks - Single-turn LLM calls with prompt templates
  • Capabilities - Built-in tools like web search and fetch
  • Agents - Multi-turn runtimes (coming soon)

Guides

Comprehensive guides for working with runpiper:

Reference

Complete command and API references:

Deployment

Deploy runpiper on your own infrastructure:

Architecture

Deep dive into how runpiper works under the hood:

Coming Soon

These features are referenced in the codebase but not fully implemented yet:

  • Task streaming: /v1/run/{name}/stream currently returns a not-implemented error.
  • Agent runtimes: the runtime only supports tasks (agents are explicitly rejected today).
  • Constraint-aware model selection: the executor still uses a default model instead of optimizing based on task constraints.

Need Help?