Simple network programming on top of Tailscale.

Install & import

Install

The main package is @vibecook/truffle. WebSocket support uses the standard ws package and is optional.

pnpm add @vibecook/truffle
pnpm add ws   # optional, only for mesh.ws

import {
  createMeshNode,
  Peer,
  resolveSidecarPath,
  NapiNode,
} from '@vibecook/truffle';

Orientation

API map

Everything hangs off a started MeshNode. Use this map to choose the right altitude for a feature.

Mesh node

createMeshNode(options)

Creates and starts a Truffle node, resolves the sidecar binary, wires the Tailscale auth callback before startup, and attaches transport namespaces.

const mesh = await createMeshNode({
  appId: 'my-app',
  deviceName: 'alice-laptop',
  onAuthRequired: (url) => console.log(url),
});

const peers = await mesh.getPeers();
const bob = await mesh.peer('bob-laptop', { waitMs: 5000 });
if (bob) await bob.send('chat', Buffer.from('hello'));

CreateMeshNodeOptions

MeshNode shape

type PeerLike = Peer | string; // string = query, resolved internally

type MeshNode = {
  // Namespaces
  net: TruffleNet;
  http: TruffleHttp;
  quic: TruffleQuic;
  dgram: TruffleDgram;
  ws: TruffleWs;
  serve: TruffleServe;
  native: NapiNode;

  // Identity / discovery
  readonly dnsName: string | null;
  getLocalInfo(): NapiNodeIdentity;
  getPeers(): Promise<Peer[]>;
  peer(query: string, opts?: { waitMs?: number }): Promise<Peer | null>;
  ping(to: PeerLike): Promise<NapiPingResult>;
  health(): Promise<NapiHealthInfo>;
  onPeerChange(cb: (event: MeshPeerEvent) => void): void;

  // Messaging — prefer explicit wire types over legacy send/broadcast
  send(to: PeerLike, namespace: string, data: Buffer | Uint8Array): Promise<void>;
  sendJson(peerId: string, namespace: string, payload: unknown): Promise<void>;
  sendBytes(peerId: string, namespace: string, data: Buffer): Promise<void>;
  broadcast(namespace: string, data: Buffer): Promise<void>;
  broadcastJson(namespace: string, payload: unknown): Promise<NapiBroadcastReport>;
  broadcastBytes(namespace: string, data: Buffer): Promise<NapiBroadcastReport>;
  onMessage(namespace: string, cb: (msg: MeshNamespacedMessage) => void): void;

  // Raw dials
  openTcp(to: PeerLike, port: number): Promise<NapiTcpSocket>;
  connectQuic(to: PeerLike, port: number): Promise<NapiQuicConnection>;

  // Subsystems
  fileTransfer(): MeshFileTransfer;
  syncedStore(id: string): NapiSyncedStore;
  proxy(): NapiProxy;
};

type MeshPeerEvent = {
  type: string;          // joined | left | updated | identity | ws_connected | …
  peerId: string;        // Tailscale routing key when peer-related
  peer?: Peer;           // interned handle when present
  authUrl?: string;
};

type MeshNamespacedMessage = {
  from: Peer | string;   // Peer when sender is interned
  namespace: string;
  msgType: string;
  payload: unknown;
  timestamp?: number;
};

Identity & discovery

Peer handles (RFC 022)

Networking takes Peer handles (or a query string). Do not pick between ULID and Tailscale id for send / connect. A peer’s deviceId is an honest ULID or null — never a Tailscale id fallback. Use deviceId only to persist across process restarts; rebind with mesh.peer(savedId, { waitMs }).

class Peer

// Preferred collections
const sessions = new Map(); // Map<Peer, AppSession>
mesh.onPeerChange((ev) => {
  if (ev.type === 'joined' && ev.peer) sessions.set(ev.peer, openSession(ev.peer));
  if (ev.type === 'left' && ev.peer) sessions.delete(ev.peer);
});

// Persistence across restarts — only place durable ids appear
if (peer.deviceId) localStorage.setItem('lastPeer', peer.deviceId);
const id = localStorage.getItem('lastPeer');
const again = id ? await mesh.peer(id, { waitMs: 5000 }) : null;

Transport

mesh.net — TCP streams

Node-style TCP over the mesh. TruffleSocket is a stream.Duplex; TruffleServer emits listening, connection, close, and error. Connect targets are PeerLike.

const server = mesh.net.createServer((socket) => {
  socket.pipe(socket);
});
server.listen(7000);

const bob = await mesh.peer('bob-laptop', { waitMs: 5000 });
const socket = mesh.net.connect({ peer: bob ?? 'bob-laptop', port: 7000 });
// host: PeerLike also accepted — mesh.net.connect({ host: bob, port: 7000 })
// Node-style: mesh.net.connect(7000, bob)
socket.on('connect', () => socket.write('ping'));
socket.on('data', (chunk) => console.log(chunk.toString()));

Transport

mesh.http — HTTP over mesh TCP

Outbound HTTP is a node:http agent that dials peers through mesh.net. Inbound HTTP uses mesh.http.createServer (drop-in http.Server on the mesh) or an ordinary server fed by mesh TCP sockets. Every mesh connection carries verified Tailscale identity on req.socket.

// Serve (Express / Fastify / plain handlers attach unchanged)
const server = mesh.http.createServer((req, res) => {
  res.end(JSON.stringify({ ok: true, path: req.url }));
});
server.listen(8080, () => {
  console.log(`http://${mesh.dnsName ?? 'device'}:8080/`);
});

// Client helpers
const res = await mesh.http.fetchText('bob-laptop', 8080, '/health');

// Or dial with a Peer yourself
const bob = await mesh.peer('bob-laptop', { waitMs: 5000 });
if (bob) mesh.net.connect({ peer: bob, port: 8080 });

Transport

mesh.dgram — UDP datagrams

Node-style datagram API. Preserves message boundaries; emits message, listening, error, and close. Send address is PeerLike.

const sock = mesh.dgram.createSocket();
sock.on('message', (msg, rinfo) => {
  console.log(rinfo.peerName ?? rinfo.address, msg.toString());
});
await sock.bind(9999);

const bob = await mesh.peer('bob-laptop', { waitMs: 5000 });
sock.send(Buffer.from('ping'), 9999, bob ?? 'bob-laptop');

Transport

mesh.ws — WebSocket over mesh TCP

Thin wrappers over the standard ws package. Optional and loaded lazily — install ws only in apps that use this namespace. connect host is PeerLike.

const wss = await mesh.ws.createServer({ port: 7788, path: '/chat' });
wss.on('connection', (ws, req) => {
  ws.on('message', (data) => ws.send('echo: ' + data.toString()));
});

const bob = await mesh.peer('bob-laptop', { waitMs: 5000 });
const ws = await mesh.ws.connect(bob ?? 'bob-laptop', 7788, '/chat');
ws.once('open', () => ws.send('hello'));

Transport

mesh.quic — multiplexed streams

QUIC connections carry many concurrent bidirectional byte streams. Streams are stream.Duplex instances; connections and servers are async iterable. connect takes PeerLike.

const server = await mesh.quic.listen(9420);
(async () => {
  for await (const conn of server.connections()) {
    (async () => {
      for await (const stream of conn.streams()) {
        stream.pipe(stream);
      }
    })();
  }
})();

const bob = await mesh.peer('bob-laptop', { waitMs: 5000 });
const conn = await mesh.quic.connect(bob ?? 'bob-laptop', 9420);
const stream = await conn.openStream();
stream.write('hello');
stream.end();

Publish

mesh.serve — declarative HTTP on the tailnet

Publish a local service or directory to the whole tailnet (RFC 023). TLS defaults on (browser audience / MagicDNS certs). Resolves with a ServeHandle ({ id, url, port, config, close() }.

// Expose a local dev server
const h = await mesh.serve({ port: 443, target: 'http://localhost:3000' });
console.log(h.url); // https://myapp.tail1234.ts.net

// Static SPA
await mesh.serve({ port: 443, dir: './public', fallback: '/index.html' });

// Mixed routes (SPA + API)
await mesh.serve({
  port: 443,
  routes: {
    '/api': 'http://localhost:8000',
    '/grafana': { target: 'http://localhost:3001' },
    '/': { dir: './public', fallback: '/index.html' },
  },
});

Application API

Namespaced messaging

Messages are routed by namespace over Truffle’s internal session transport. Prefer explicit wire types — sendJson / sendBytes and their broadcast counterparts — so the wire type never depends on the data’s contents. Legacy send / broadcast still content-sniff UTF-8 JSON.

mesh.onMessage('chat', async (msg) => {
  if (typeof msg.from === 'string') return;
  console.log(msg.from.displayName, msg.msgType, msg.payload);
  await msg.from.sendJson('chat', { text: 'ack' });
});

const peer = (await mesh.getPeers())[0];
if (peer) {
  await peer.sendJson('chat', { text: 'hello' });
  await peer.sendBytes('bin', Buffer.from([0x01, 0x02]));
}

// Broadcast only reaches peers with an active session (no lazy dial).
// broadcastJson / broadcastBytes return a NapiBroadcastReport.
const report = await mesh.broadcastJson('chat', { text: 'hello everyone' });
console.log(report.queued, '/', report.attempted, 'queued');

Application API

File transfer

mesh.fileTransfer() returns a handle for push, pull, offers, progress events, max-size policy, and pull-root policy. Targets accept PeerLike (Peer | string).

const ft = mesh.fileTransfer();

ft.onOffer((offer, responder) => {
  responder.accept('/tmp/' + offer.fileName);
});

ft.onEvent((event) => console.log(event.eventType, event.progress));

const peer = (await mesh.getPeers())[0];
if (peer) {
  await ft.sendFile(peer, './report.pdf', '/tmp/report.pdf');
}

Application API

Synced stores

A synced store holds device-owned JSON slices. Each device updates its own slice and observes slices from peers. Slice keys are durable device ULIDs — store identity, not a networking address. Prefer Peer handles for dial/send; use store deviceId to correlate slices after identity is known.

const store = mesh.syncedStore('presence');

store.onChange((event) => console.log(event));
await store.set({ status: 'online', file: 'notes.md' });

console.log(await store.local());
console.table(await store.all());

// Correlate a slice with a live Peer after identity is known
const me = mesh.getLocalInfo().deviceId;
for (const slice of await store.all()) {
  if (slice.deviceId === me) continue;
  const peer = await mesh.peer(slice.deviceId, { waitMs: 0 });
  if (peer) console.log(peer.displayName, slice.data);
}

Publish

Reverse proxy

mesh.proxy() exposes local services on mesh ports and can announce them for discovery. Prefer mesh.serve for the common “publish a directory or localhost process” cases — serve is sugar over this engine.

const proxy = mesh.proxy();
const info = await proxy.add({
  id: 'local-api',
  name: 'Local API',
  listenPort: 8443,
  targetHost: 'localhost',
  targetPort: 3000,
  targetScheme: 'http',
  announce: true,
});

React

@vibecook/truffle-react

Thin hooks around an already-started node. Prefer a MeshNode from createMeshNode() and pass mesh.native where hooks still expect NapiNode. Hook peer snapshots currently track native NapiPeer fields; send helpers still take a peer query string. For handle-first networking, keep Peers from mesh.getPeers() / events and call peer.send yourself.

import { useMesh, useAuth, useSyncedStore } from '@vibecook/truffle-react';

function Peers({ node }) {
  const { peers, send, broadcast } = useMesh(node);
  const auth = useAuth(node);
  const presence = useSyncedStore(node, 'presence');

  // send still takes a query string today
  // await send(peers[0]?.deviceId ?? peers[0]?.displayName, 'chat', { text: 'hi' });
}

Lower-level handles

Native classes

The package re-exports classes and types from @vibecook/truffle-native for apps that need the lower-level pull-model handles. Prefer createMeshNode() for the TS Peer registry and stream wrappers.

Companion

CLI commands

Useful for manual operations, debugging, and agent automation. Apps should integrate the JavaScript API as the product surface.

Install

# macOS / Linux
curl -fsSL https://vibecook-dev.github.io/truffle/install.sh | sh

# Windows
iwr -useb https://vibecook-dev.github.io/truffle/install.ps1 | iex

Quick start

truffle up                          # start node / daemon
truffle ls                          # list peers
truffle send laptop "deploy is done"
truffle cp ./report.pdf server:/tmp/
truffle serve http://localhost:3000 --port 443
truffle ping laptop

Additional commands

truffle
truffle up --device-name alice-laptop
truffle down
truffle status --json
truffle ls --long
truffle ping bob-laptop -c 4
truffle tcp bob-laptop:7000
truffle send bob-laptop "hello"
truffle cp ./report.pdf bob-laptop:/tmp/
truffle serve http://localhost:3000 --port 443
truffle serve ./public --port 443 --fallback /index.html
truffle serve status
truffle serve stop serve-443
truffle watch --json
truffle wait bob-laptop --timeout 30
truffle recv --from bob-laptop --timeout 30
truffle proxy add --name api --target-port 3000 --listen-port 8443
truffle proxy list
truffle doctor
truffle update

Platforms

Truffle Swift (RFC 024)

An Apple-native SPM package under apple/ implements the same mesh product model — Peers, appId isolation, namespaced messages — wire-compatible with truffle-core. It is designed for in-process embedding on iOS/macOS via libtailscale / TailscaleKit (no desktop sidecar).