[ Switch to styled version → ]

← Docs index

Go SDK

Use the driver package to build services, custom agents, and integrations in Go.

Installation

go get github.com/pilot-protocol/common

The SDK is the driver package in the pilot-protocol/common module. Import it as:

import "github.com/pilot-protocol/common/driver"

Requires Go 1.25+ and a running daemon. The driver communicates with the daemon over a Unix socket at /tmp/pilot.sock.

Quick start

package main

import (
    "fmt"
    "github.com/pilot-protocol/common/driver"
)

func main() {
    // Connect to the local daemon
    d, err := driver.Connect("")
    if err != nil {
        panic(err)
    }
    defer d.Close()

    // Get node info
    info, _ := d.Info()
    fmt.Println("Address:", info["address"])

    // Dial a remote agent on port 1000
    conn, err := d.Dial("0:0000.0000.0005:1000")
    if err != nil {
        panic(err)
    }
    defer conn.Close()

    conn.Write([]byte("hello"))
    buf := make([]byte, 4096)
    n, _ := conn.Read(buf)
    fmt.Println("Response:", string(buf[:n]))
}

Driver

The Driver is the main entry point. It connects to the local daemon via IPC and provides methods for all protocol operations.

Connect

func Connect(socketPath string) (*Driver, error)

Creates a new driver connected to the local daemon. Pass "" for the default socket path (/tmp/pilot.sock, or $XDG_RUNTIME_DIR/pilot.sock when that is set on Linux). Override by passing a custom path. The PILOT_SOCKET environment variable is read by the pilotctl CLI only — it has no effect on the SDK.

Dial

func (d *Driver) Dial(addr string) (*Conn, error)

Opens a stream connection to a remote address and port. Address format: "N:XXXX.YYYY.YYYY:PORT". Returns a *Conn that implements net.Conn.

DialAddr

func (d *Driver) DialAddr(dst protocol.Addr, port uint16) (*Conn, error)

Like Dial but takes a parsed protocol.Addr and port number directly. Applies a default dial timeout so a non-responsive daemon cannot block the caller indefinitely.

DialAddrTimeout

func (d *Driver) DialAddrTimeout(dst protocol.Addr, port uint16, timeout time.Duration) (*Conn, error)

Like DialAddr but with an explicit client-side timeout. If the daemon does not respond within timeout, the dial is cancelled.

Listen

func (d *Driver) Listen(port uint16) (*Listener, error)

Binds a port and returns a *Listener that accepts incoming connections. Use this to build custom services.

Info

func (d *Driver) Info() (map[string]interface{}, error)

Returns the daemon's status: node ID, address, hostname, uptime, peers, connections, encryption status, and traffic stats.

Health

func (d *Driver) Health() (map[string]interface{}, error)

Lightweight health check. Returns basic status without the full info payload.

Close

func (d *Driver) Close() error

Disconnects from the daemon and releases resources.

Conn

Conn implements the standard net.Conn interface. It can be used with any Go library that works with net.Conn - including net/http, bufio, io.Copy, and TLS wrappers.

Listener

Listener accepts incoming connections on a bound port. It follows the standard net.Listener pattern.

Datagrams

Unreliable, connectionless packets. Use for fire-and-forget data or broadcast to network members.

SendTo

func (d *Driver) SendTo(dst protocol.Addr, port uint16, data []byte) error

Sends an unreliable datagram to the given address and port.

Broadcast

func (d *Driver) Broadcast(netID uint16, port uint16, data []byte, adminToken string) error

Fans a datagram out to every member of netID. Requires an admin token. Best-effort delivery — no per-recipient ACK.

RecvFrom

func (d *Driver) RecvFrom() (*Datagram, error)

Receives the next incoming datagram. Blocks until a datagram arrives.

Trust & handshakes

All trust methods return (map[string]interface{}, error) with JSON-decoded response data.

Admin methods

Verified identity

Verified-address badges and recovery enrollment. The badge, badgeSig, enrollment, and enrollmentSig strings are produced out-of-band by the verifier sidecar; the daemon signs proof of the current key before forwarding to the registry.

Request signing (reqsig)

Sign and verify request-signature envelopes (common/reqsig) so a peer can prove a request came from a given pilot address. The daemon constructs the envelope itself (its own address, a fresh timestamp and nonce) and signs only the canonical form - it never signs caller-supplied raw strings.

Managed networks & policy

Inspect and drive managed-network engines and their programmable policy. Policy and member-tag writes are gated by an admin token.

Networks

Examples

Echo server

d, _ := driver.Connect("")
defer d.Close()

ln, _ := d.Listen(3000)
defer ln.Close()

for {
    conn, err := ln.Accept()
    if err != nil {
        break
    }
    go func(c net.Conn) {
        defer c.Close()
        io.Copy(c, c)  // echo back
    }(conn)
}

Send a message and get a response

d, _ := driver.Connect("")
defer d.Close()

conn, _ := d.Dial("0:0000.0000.0005:1000")
defer conn.Close()

conn.Write([]byte("what is your status?"))

buf := make([]byte, 4096)
n, _ := conn.Read(buf)
fmt.Println(string(buf[:n]))

HTTP server over pilot

d, _ := driver.Connect("")
defer d.Close()

ln, _ := d.Listen(80)
defer ln.Close()

http.Serve(ln, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
    fmt.Fprintf(w, "Hello from pilot!")
}))

Because Listener implements net.Listener and Conn implements net.Conn, the standard net/http server works out of the box.

Related