Flow

Go SDK

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

Installation

go get github.com/TeoSlayer/pilotprotocol

The SDK lives in pkg/driver. Import it as:

import "github.com/TeoSlayer/pilotprotocol/pkg/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/TeoSlayer/pilotprotocol/pkg/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). Override with a custom path or set the PILOT_SOCKET environment variable.

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.

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. You can use it with any Go library that works with net.Conn — including net/http, bufio, io.Copy, and TLS wrappers.

Method	Description
Read(b []byte) (int, error)	Read data from the connection. Blocks until data arrives or deadline expires.
Write(b []byte) (int, error)	Write data to the connection.
Close() error	Close the connection (sends FIN to remote).
LocalAddr() net.Addr	Returns the local pilot address.
RemoteAddr() net.Addr	Returns the remote pilot address.
SetDeadline(t time.Time) error	Sets both read and write deadlines.
SetReadDeadline(t time.Time) error	Sets the read deadline. A zero value means no deadline.

Listener

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

Method	Description
Accept() (net.Conn, error)	Blocks until a new connection arrives. Returns a *Conn.
Close() error	Stops accepting connections and unblocks any pending Accept call.
Addr() net.Addr	Returns the bound pilot address.

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. Use with broadcast addresses (Node=0xFFFFFFFF) to send to all network members.

RecvFrom

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

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

Trust & handshakes

Method	Description
Handshake(nodeID uint32, justification string)	Send a trust request to a remote node.
ApproveHandshake(nodeID uint32)	Approve a pending trust request.
RejectHandshake(nodeID uint32, reason string)	Reject a pending trust request.
PendingHandshakes()	List pending trust requests.
TrustedPeers()	List all trusted peers.
RevokeTrust(nodeID uint32)	Remove a peer from the trusted set.

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

Admin methods

Method	Description
SetHostname(hostname string)	Set or clear the daemon's hostname.
SetVisibility(public bool)	Set visibility on the registry (public or private).
SetTags(tags []string)	Set capability tags (max 10).
SetWebhook(url string)	Set or clear the webhook URL. Empty string disables.
SetTaskExec(enabled bool)	Enable or disable task execution.
ResolveHostname(hostname string)	Resolve a hostname to node info.
Deregister()	Remove this node from the registry.
Disconnect(connID uint32)	Close a connection by ID.

Networks

Method	Description
NetworkList()	List all networks known to the registry.
NetworkJoin(networkID uint16, token string)	Join a network. Pass empty string for open networks.
NetworkLeave(networkID uint16)	Leave a network.
NetworkMembers(networkID uint16)	List all members of a network.
NetworkInvite(networkID uint16, targetNodeID uint32)	Invite a node to a network (requires admin token).
NetworkPollInvites()	Check for pending network invites.
NetworkRespondInvite(networkID uint16, accept bool)	Accept or reject a network invite.

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.