runkite-runner

Python runner for Runkite — a self-hosted Agent Protocol control plane.

This package is the process that does the work: it connects to a Runkite control plane over gRPC, claims jobs, loads your agent from langgraph.json, executes it (LangGraph by default), and streams events, heartbeats, and terminal status back so clients see live SSE / WebSocket progress in the Admin UI.

  Client / SDK ──HTTP/SSE──► Runkite control plane (Go)
                                    │ gRPC Runner Protocol
                                    ▼
                           runkite-runner (this package)
                                    │
                              your LangGraph agent

Why a separate runner?

Runkite keeps the control plane framework-agnostic (auth, threads, runs, queues, Admin UI). Framework-specific execution lives in a runner so you can scale workers independently, mix Python and TypeScript agents on one plane, and upgrade LangGraph without redeploying the Go binary.

Install

pip install runkite-runner

Requires Python 3.11+. Pulls in LangGraph, gRPC, checkpoint Postgres support, httpx, and uvicorn (see pyproject.toml). Tracing is optional:

pip install 'runkite-runner[otel]'

Without the extra, the runner still starts; OTEL_* env vars log once and stay no-op until the packages are installed.

Quick start

1. Control plane (pick one):

# Docker
docker pull ghcr.io/getrunkite/runkite:latest
docker run --rm -p 2026:2026 -p 50051:50051 \
  -e RUNKITE_ALLOW_INSECURE_SERVE=1 \
  ghcr.io/getrunkite/runkite:latest \
  dev --config /app/examples/echo_agent/langgraph.json

# or binary from https://github.com/getrunkite/runkite/releases

2. Runner (this package):

runkite-runner \
  --config path/to/langgraph.json \
  --grpc-address 127.0.0.1:50051 \
  --http-address http://127.0.0.1:2026

3. Admin UI: http://127.0.0.1:2026/admin/

Minimal langgraph.json:

{
  "graphs": {
    "echo_agent": "./graph.py:graph"
  },
  "dependencies": ["."]
}

Examples live in the Runkite repo (echo_agent, react_agent, approval_agent, …).

Features

• LangGraph graphs with streaming chunks, cancel, and HITL interrupt/resume
• Durable checkpoints via AsyncPostgresSaver when POSTGRES_DSN is set; otherwise in-process MemorySaver (fine for local demos)
• Store / vector dual-mode against the control plane’s APIs
• Concurrency — --concurrency N / RUNKITE_CONCURRENCY for overlapping I/O-bound jobs
• OpenTelemetry — runkite.run span under the control plane traceparent, plus thin runkite.llm / runkite.tool children when OTLP env is set
• Production auth — runner kind tokens (RUNNER_TOKEN / RUNNER_TOKEN_*) matching control-plane config

Framework adapters (same repo, not separate PyPI packages yet)

CrewAI, LlamaIndex, AutoGen, and plain LangChain runners live under python/adapters/ in the Runkite source tree and share runkite_runner.generic_worker. Install those from a clone with an isolated venv when you need them — see docs/runners.md.

Configuration

Related artifacts

Links

• Homepage: https://getrunkite.github.io/runkite/
• Source: https://github.com/getrunkite/runkite/tree/main/python
• Issues: https://github.com/getrunkite/runkite/issues
• Changelog: https://github.com/getrunkite/runkite/blob/main/CHANGELOG.md
• Known limitations: https://github.com/getrunkite/runkite/blob/main/docs/limitations.md
• Security: https://github.com/getrunkite/runkite/blob/main/SECURITY.md