Your laptop / VM
LangGraph (your code)
- PilotRemoteRunnable
- PilotFanoutRunnable
- PilotCheckpointSaver
unix socket
pilot-daemon
langgraph-pilot is a Python package that lets a LangGraph node execute on a different machine, with graph state persisted across the network — over end-to-end encrypted Pilot Protocol tunnels. NAT-traversed. Mutually authenticated. No public ports, no API gateway, no central broker.
A PilotRemoteRunnable
looks and feels like any other LangChain Runnable — ainvoke /
astream, retries, callbacks, RunnableConfig propagation —
but the work happens on a remote pilot peer. The peer can be a laptop, a
phone, an on-prem server, a cloud VM. Trust gates every call.
A PilotCheckpointSaver
ships every graph checkpoint to a remote peer's SQLite store, idempotent
on retry, so graph state survives process restarts and lives on a
different machine than the graph that wrote it.
# A graph that fans out to 3 remote workers in parallel # and persists state on a 4th, all over Pilot tunnels. from langgraph.graph import StateGraph from pilot_langgraph import ( PilotRemoteRunnable, PilotFanoutRunnable, PilotCheckpointSaver, ) graph = StateGraph(MyState) graph.add_node("research", PilotFanoutRunnable({ "broad": PilotRemoteRunnable(node="search", peer="worker-a"), "deep": PilotRemoteRunnable(node="search", peer="worker-b"), "novel": PilotRemoteRunnable(node="search", peer="worker-c"), })) app = graph.compile( checkpointer=PilotCheckpointSaver(peer="state-worker"), )
# From pilotprotocol.network curl -fsSL https://pilotprotocol.network/install.sh | sh pilotctl daemon start \ --hostname my-host \ --email you@example.com
# From PyPI (coming soon) or source: pip install \ git+https://github.com/TeoSlayer/pilot-langgraph # Run a worker: pilot-langgraph-worker \ --handlers my_handlers --port 5000
Worker handlers are plain Python functions decorated with @pilot_handler("name").
Each handler can take per-handler ACL, timeouts, rate limits, max-concurrent
semaphores, and pydantic input/output validation. The full surface and a
60-second quickstart live in the
README.
PilotRemoteRunnable — async-first LangChain Runnable, multiplexed concurrent calls share one connection, transparent reconnect, configurable retry, optional pydantic validation.
PilotFanoutRunnable dispatches one input to N targets in parallel. Native LangGraph Send API supported for dynamic data-dependent fanout.
PilotCheckpointSaver ships every checkpoint to a remote peer. Idempotent retries, SQLite-backed store, graph state survives process restarts.
Decorate any handler with @pilot_handler("name", allow=[node_id, ...]) and only the listed peers can call it. Default-open or default-closed.
Sliding-window rate_per_caller, hard timeout_secs, max_concurrent semaphore. Typed errors come back to the caller with structured metadata.
Async-generator handlers stream chunks to the caller's astream. Pub/sub channels (PilotChannel) for many-to-many topics with auto-reconnect.
Prometheus /metrics + /healthz via --metrics-port. JSON logging with request_id correlation. OpenTelemetry W3C trace propagation across the wire.
Auto-registered _health + _handlers introspection (with JSON schemas), graceful SIGTERM drain, periodic tasks, dev --reload, middleware chain.
Ships with a systemd unit, a Dockerfile, and a docker-compose example. Worker auto-discoverable via tools/discover.py.
Each Pilot daemon assigns the host a 48-bit virtual address. Trusted peers reach each other by address or hostname; the rendezvous server handles only discovery and NAT hole-punching — your data flows directly between daemons, AES-256-GCM encrypted, signed by Ed25519 identities.
| You want | What langgraph-pilot gives you |
|---|---|
| Distributed agents | A LangGraph node that runs on another machine. No HTTP wrapper, no API gateway, no service-mesh. The remote peer dials the local daemon's Unix socket; nothing is exposed to the public internet. |
| State across restarts | A checkpoint store that lives on a different host than the graph. Your laptop crashes; the workflow resumes against the persisted state on the worker. Idempotent retries; SQLite or in-memory. |
| Cross-org workflows | Mutual trust gates every call. Per-handler ACL means even a trusted peer can only call the handlers it's been allowlisted for. Workflows that span organizational boundaries with no shared infra. |
| Multi-region fanout | PilotFanoutRunnable dispatches one input to N peers in parallel. Each branch lands on a physically distinct VM; result includes the worker's hostname so you can prove it. |
| NAT-bound workers | NAT traversal is built in. Workers behind home routers, dynamic IPs, mobile networks — Pilot's UDP hole-punching gets through. No port forwarding, no VPN. |
| Observability | Prometheus metrics, JSON logs, OpenTelemetry traces. RunnableConfig callbacks fire normally for every remote call — LangSmith works untouched. |
PilotRemoteRunnable and use it like any LangGraph node. The Runnable speaks to a local pilot-daemon over a Unix socket; the daemon establishes an encrypted tunnel to the worker's daemon, which dispatches to a handler decorated with @pilot_handler('name'). Both ainvoke and astream are supported, and concurrent calls multiplex over a single connection.
PilotCheckpointSaver is a BaseCheckpointSaver subclass that ships every checkpoint to a remote peer's store (SQLite by default; in-memory available). Writes are idempotent on retry via UNIQUE constraints. The graph that wrote the state can crash and a fresh process — even on a different machine — can resume from the same thread_id.
PilotRemoteRunnable participates fully in the RunnableConfig propagation chain — on_chain_start, on_chain_end, and on_chain_error fire normally for every remote call, so LangSmith and any other LangChain CallbackHandler work without code changes. OpenTelemetry W3C trace context is also propagated across the wire.
allow=[node_id, ...] so even a trusted peer is rejected if it isn't on the explicit allowlist. Per-handler timeout_secs, sliding-window rate_per_caller, and max_concurrent semaphores are also available.
Pilot is a peer-to-peer overlay network for AI agents. Every daemon gets an Ed25519 identity, a 48-bit virtual address, NAT-traversed tunnels, and AES-256-GCM encryption per session. langgraph-pilot is one of the first frameworks built on top of it. Read the spec, see the live network, install it for your own agents.