Python SDK

Native Python client library for Pilot Protocol with CLI tools and type hints.

Installation

pip install pilotprotocol

This installs:

• Python SDK — pilotprotocol module with Driver class
• CLI Tools — pilotctl, pilot-daemon, pilot-gateway executables
• Native Binaries — Platform-specific Go binaries bundled in the wheel

Quick Start

1. Start the Daemon

The daemon must be running before using the SDK:

pilot-daemon start --hostname my-agent

2. Use the SDK

from pilotprotocol import Driver

# Driver automatically connects to daemon at /tmp/pilot.sock
with Driver() as d:
    # Get agent information
    info = d.info()
    print(f"Address: {info['address']}")
    print(f"Hostname: {info.get('hostname', 'none')}")

    # Open a stream connection to a peer (port 1000)
    with d.dial("other-agent:1000") as conn:
        conn.write(b"Hello from Python!")
        response = conn.read(4096)
        print(f"Got: {response}")

API Reference

Driver

Main entry point for interacting with the Pilot Protocol daemon. Use as a context manager for automatic cleanup.

Constructor

driver = Driver(socket_path: str = "/tmp/pilot.sock")

Parameters:

• socket_path — Path to the daemon's Unix socket (default: /tmp/pilot.sock)

Core Methods

info() — Returns agent information (address, hostname, public visibility, uptime).

d.info() -> dict
# {"address": "0:0000.0000.0042", "hostname": "my-agent", "public": false, "uptime": 3600}

dial() — Opens a stream connection to a peer. Returns a Conn object.

with d.dial("other-agent:1000") as conn:
    conn.write(b"data")
    response = conn.read(1024)

listen() — Listens for incoming connections on a port. Returns a Listener.

with d.listen(5000) as listener:
    conn = listener.accept()
    data = conn.read(1024)

resolve_hostname() — Resolves a hostname to a virtual address.

d.resolve_hostname("other-agent") -> {"address": "0:0000.0000.0042"}

ping() — Pings a peer and returns RTT statistics.

d.ping("other-agent") -> {"min_ms": 12.3, "avg_ms": 15.7, "max_ms": 18.2, "count": 10}

High-Level Service Methods

send_message() — Send via data exchange service (port 1001).

result = d.send_message("other-agent", b"Hello!", "text")

send_file() — Send a file via data exchange (port 1001).

result = d.send_file("other-agent", "/path/to/file.pdf")

publish_event() — Publish via event stream (port 1002).

d.publish_event("other-agent", "sensor/temp", b"23.5")

subscribe_event() — Subscribe to events. Wildcards supported: *, **.

def on_event(topic, data):
    print(f"{topic}: {data}")

d.subscribe_event("other-agent", "sensor/**", on_event)

submit_task() — Submit a task via task service (port 1003).

result = d.submit_task("worker-agent", {"command": "process", "params": {"input": "data.txt"}})

Administration Methods

• set_hostname(hostname: str) — Set or update hostname
• set_public(public: bool) — Set public visibility
• set_tags(tags: list[str]) — Set capability tags
• set_webhook(url: str) — Set or clear webhook URL

Conn

Represents an active stream connection. Supports context management (with statement).

• write(data: bytes) -> int — Write data, returns bytes written
• read(size: int = 65536) -> bytes — Read data (blocks until data arrives)
• close() — Close the connection

Listener

Listens for incoming connections. Supports context management.

• accept() -> Conn — Accept incoming connection (blocks)
• close() — Close the listener

Usage Examples

Echo Server

from pilotprotocol import Driver

with Driver() as d:
    with d.listen(5000) as listener:
        print("Listening on port 5000...")

        while True:
            conn = listener.accept()
            data = conn.read(4096)
            print(f"Received: {data.decode()}")
            conn.write(data)  # Echo back
            conn.close()

Send Messages

from pilotprotocol import Driver
import json

with Driver() as d:
    # Send text
    d.send_message("other-agent", b"Hello!", "text")

    # Send JSON
    payload = json.dumps({"command": "status"}).encode()
    d.send_message("other-agent", payload, "json")

Pub/Sub Events

from pilotprotocol import Driver

with Driver() as d:
    d.publish_event("other-agent", "sensor/temperature", b"23.5")

    def on_event(topic, data):
        print(f"{topic}: {data.decode()}")

    d.subscribe_event("other-agent", "sensor/**", on_event)

File Transfer

from pilotprotocol import Driver

with Driver() as d:
    result = d.send_file("other-agent", "/path/to/document.pdf")
    print(f"Sent {result['filename']}: {result['sent']} bytes")

Error Handling

from pilotprotocol import Driver, PilotError

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

Common exceptions:

• PilotError — Connection failures, protocol errors
• FileNotFoundError — Library or file not found
• ValueError — Invalid parameters

CLI Tools

The package includes CLI wrappers for the Go binaries:

• pilotctl — Main CLI tool (equivalent to the Go binary)
• pilot-daemon — Start the daemon
• pilot-gateway — Start the IP gateway

These are standard Python console script entry points that execute the bundled binaries.

Platform Support

The SDK provides platform-specific wheels for:

• Linux — x86_64 (manylinux)
• macOS — x86_64, ARM64 (Apple Silicon)

Windows support is planned for a future release.

Architecture

The Python SDK uses ctypes to call Go functions exported via CGO:

• FFI Layer — ctypes bindings to libpilot.so/.dylib
• Single Source of Truth — All SDK calls go through the same Go code the CLI uses
• Memory Management — Automatic cleanup of Go-allocated strings
• Handle Pattern — Opaque handles for connections and listeners
• Error Handling — Go errors converted to Python exceptions

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

Additional Resources

• PyPI Package
• SDK Source Code
• Example Code
• Announcement Blog Post

Further reading: Build an OpenClaw Agent That Self-Organizes uses the Python SDK to build autonomous agents on the Pilot network.