Announcing the Pilot Protocol Python SDK

v0.1.1

Why a Python SDK

Pilot Protocol's core daemon is written in Go and distributed as a static binary with no external runtime dependencies. That's a strength for deployment but a friction point for the Python ecosystem. AI/ML engineers, data scientists, and agent framework developers overwhelmingly work in Python. Asking them to shell out to pilotctl and parse CLI output is not a real integration.

The Python SDK gives you a native Driver class with context managers, type hints, and Pythonic error handling. Under the hood it calls the same Go code through a ctypes FFI layer - same guarantees, no re-implementation.

pip install pilotprotocol

One command installs the SDK, the CLI tools (pilotctl, pilot-daemon), and platform-specific native binaries. Python 3.9+, Linux and macOS.

Hello World in 8 Lines

Start the daemon, then:

from pilotprotocol import Driver

with Driver() as d:
    info = d.info()
    print(f"I am {info['hostname']} at {info['address']}")

    with d.dial("other-agent:1000") as conn:
        conn.write(b"Hello from Python!")
        print(conn.read(4096))

The Driver connects to the daemon's Unix socket at /tmp/pilot.sock. The with statement handles cleanup. dial() returns a Conn that supports read(), write(), and close() - exactly what you'd expect from a socket.

High-Level API: Services Without Boilerplate

The SDK wraps Pilot's built-in services so you don't have to deal with port numbers or wire formats:

with Driver() as d:
    # Data exchange (port 1001)
    d.send_message("peer", b"status update", "text")
    d.send_file("peer", "/models/weights.bin")

    # Pub/sub events (port 1002)
    d.publish_event("peer", "metrics/gpu", b"87.3")
    d.subscribe_event("peer", "metrics/**", lambda topic, data: print(f"{topic}: {data}"))

Each method handles connection setup, framing, and acknowledgment. You send bytes and get dicts back.

Low-Level Streams: Build Your Own Protocol

For custom protocols, use dial() and listen() directly:

from pilotprotocol import Driver

# Server side
with Driver() as d:
    with d.listen(5000) as listener:
        while True:
            conn = listener.accept()
            data = conn.read(4096)
            conn.write(data)  # Echo
            conn.close()

This gives you raw bidirectional streams over Pilot's encrypted tunnels. Every connection gets X25519 + AES-256-GCM encryption automatically - no TLS configuration, no certificate management.

Architecture: ctypes FFI to Go

The SDK doesn't re-implement any protocol logic. It calls into a shared library (libpilot.so / libpilot.dylib) built from the same Go source code that powers the CLI:

┌─────────────┐    ctypes/FFI    ┌──────────────┐    Unix socket    ┌────────┐
│  Python SDK │ ───────────────► │  libpilot.so │ ─────────────────► │ Daemon │
│  (client.py)│                  │  (Go c-shared)│                   │        │
└─────────────┘                  └──────────────┘                    └────────┘

This means:

• Single source of truth - the SDK uses the exact same packet handling, encryption, and transport code as pilotctl
• No drift - when the Go code gets a bug fix, the Python SDK gets it too (after a wheel rebuild)
• Memory safety - Go's GC manages allocations; the SDK handles cleanup of Go-allocated strings via ctypes
• Opaque handles - connections and listeners are represented as integer handles, avoiding cross-language pointer issues

Error Handling

Go errors become Python exceptions:

from pilotprotocol import Driver, PilotError

with Driver() as d:
    try:
        conn = d.dial("nonexistent:1000")
    except PilotError as e:
        print(f"Failed: {e}")  # "no route to host"

The SDK raises PilotError for protocol-level failures (unreachable peers, trust failures, timeouts), FileNotFoundError when the native library isn't found, and ValueError for invalid parameters. Standard Python exception hierarchy - catch what you need.

Full Type Hints

Every method, parameter, and return value is annotated. Works with mypy, pyright, and IDE autocomplete out of the box:

from pilotprotocol import Driver, Conn
from typing import Dict, Any

with Driver() as d:
    conn: Conn = d.dial("other-agent:1000")
    info: Dict[str, Any] = d.info()

Use With Agent Frameworks

The SDK is designed to integrate with existing Python agent frameworks. A few patterns:

With LangChain / LangGraph: Use the SDK as a tool - agents can send messages, transfer files, or delegate tasks to peers on the Pilot network as part of their tool chain.

With OpenClaw: The SDK powers the Pilot skill on ClawHub. OpenClaw agents use it to discover peers, establish trust, and form multi-agent pipelines.

With FastAPI / Flask: Run a local HTTP server that proxies to Pilot peers. Or use the gateway to expose Pilot services as local IPs and hit them with standard HTTP clients.

Getting Started

1. Install: pip install pilotprotocol
2. Set your hostname, then start the daemon: pilotctl init --hostname my-agent followed by pilotctl daemon start (the daemon takes its email via the -email flag, not --hostname)
3. Write Python code using the Driver class
4. See the full API reference for all methods and types

Working examples are in the Python SDK guide and the sdk-python README on GitHub.