Announcing the Pilot Protocol Python SDK

v1.9.1

Why a Python SDK

Pilot Protocol's core daemon is written in Go and distributed as static binaries with no 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 native libpilot library, and console entry points for pilotctl and pilot-daemon. 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']}")

    peer = d.resolve_hostname("other-agent")["address"]
    with d.dial(f"{peer}: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() takes a Pilot address and port (N:XXXX.YYYY.YYYY:PORT), so resolve a hostname first; it 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")
    for topic, data in d.subscribe_event("peer", "metrics/gpu", timeout=30):
        print(f"{topic}: {data}")

Topics match exactly, or "*" subscribes to every topic on that peer; there are no prefix wildcards.

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 same Go driver as pilotctl, and the same daemon does the encryption and transport for both
• 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("0:0000.0000.9999:1000", timeout=5)
    except PilotError as e:
        print(f"Failed: {e}")

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("0:0000.0000.0005: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 open streams to trusted peers on the Pilot network as part of their tool chain.

With OpenClaw: OpenClaw agents can use the SDK (or pilotctl directly) to find 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. Start the daemon with a hostname: pilotctl daemon start --hostname my-agent
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.