{"id":47623065,"url":"https://github.com/jamesyong-42/truffle","last_synced_at":"2026-04-12T00:48:34.357Z","repository":{"id":340434630,"uuid":"1166080233","full_name":"jamesyong-42/truffle","owner":"jamesyong-42","description":"P2P mesh networking for your devices, built on Tailscale. Clean 7-layer architecture with WS/TCP/UDP/QUIC transports.","archived":false,"fork":false,"pushed_at":"2026-03-29T23:52:09.000Z","size":1911,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-30T00:41:31.212Z","etag":null,"topics":["cli","cross-platform","mesh-networking","p2p","rust","tailscale","websocket"],"latest_commit_sha":null,"homepage":"https://jamesyong-42.github.io/truffle/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jamesyong-42.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T21:22:38.000Z","updated_at":"2026-03-29T23:51:59.000Z","dependencies_parsed_at":"2026-03-30T00:07:50.279Z","dependency_job_id":null,"html_url":"https://github.com/jamesyong-42/truffle","commit_stats":null,"previous_names":["jamesyong-42/truffle"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/jamesyong-42/truffle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesyong-42%2Ftruffle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesyong-42%2Ftruffle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesyong-42%2Ftruffle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesyong-42%2Ftruffle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jamesyong-42","download_url":"https://codeload.github.com/jamesyong-42/truffle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jamesyong-42%2Ftruffle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31292639,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T21:15:39.731Z","status":"ssl_error","status_checked_at":"2026-04-01T21:15:34.046Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cross-platform","mesh-networking","p2p","rust","tailscale","websocket"],"created_at":"2026-04-01T22:26:27.433Z","updated_at":"2026-04-01T22:26:28.072Z","avatar_url":"https://github.com/jamesyong-42.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Truffle\n\n[![CI](https://github.com/jamesyong-42/truffle/actions/workflows/ci.yml/badge.svg)](https://github.com/jamesyong-42/truffle/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/jamesyong-42/truffle?label=latest)](https://github.com/jamesyong-42/truffle/releases/latest)\n[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\n**Mesh networking for your devices, built on Tailscale.**\n\nTruffle lets your devices discover each other, exchange messages, and transfer files over Tailscale's encrypted WireGuard tunnels. No central server. Run `truffle` to launch an interactive TUI, or use one-shot commands for scripts and AI agents.\n\n```\n╭─── truffle ──────────────────────────────────────────────────╮\n│                                         │ Devices                │\n│  ▀█▀ █▀█ █ █ █▀▀ █▀▀ █   █▀▀          │ ● server (direct)      │\n│   █  █▀▄ █ █ █▀  █▀  █   █▀           │ ● laptop (relay)       │\n│   █  █ █ ▀▄▀ █   █   █▄▄ █▄▄          │ ○ pi (offline)         │\n│                                         │                        │\n│  mesh networking for your devices       │                        │\n│  jamess-mbp · 100.64.0.5               │                        │\n│  ● online · 2 peers · 15m              │                        │\n╰───────────────────────────────────────────────────────────────╯\n  14:02  ● server joined (direct)\n  14:03  You → server: Hello!\n  14:03  server → You: Hey there!\n  14:05  ⬇ report.pdf from server ████████████████ 100% ✓\n─────────────────────────────────────────────────────────────────\n❯ /send how are things? @server\n─────────────────────────────────────────────────────────────────\n  truffle · ● online · 2 peers\n```\n\n## Install\n\n```bash\ncurl -fsSL https://jamesyong-42.github.io/truffle/install.sh | sh\n```\n\nSupports macOS (arm64/x64), Linux (x64/arm64), and Windows (x64). Linux binaries are statically linked (musl) — works on any distro.\n\n## Quick Start\n\n### Interactive TUI\n\n```bash\ntruffle                           # launch the interactive TUI\n```\n\nFirst run shows an onboarding wizard with smart device naming and Tailscale auth. After setup, the TUI shows a live activity feed, device panel, and slash commands:\n\n| Command | Description |\n|---------|-------------|\n| `/send \u003cmsg\u003e @device` | Send a message (`@` autocompletes devices) |\n| `/broadcast \u003cmsg\u003e` | Message all online peers |\n| `/cp \u003cpath\u003e @device` | Send a file (Tab opens file picker) |\n| `/exit` | Quit |\n\nIncoming file transfers show an accept/reject modal dialog.\n\n### One-Shot Commands (for scripts \u0026 agents)\n\n```bash\ntruffle up                        # start daemon in background\ntruffle ls                        # see who's online\ntruffle status                    # node identity, IP, uptime\ntruffle ping laptop               # check latency\ntruffle send server \"hello\"       # send a message\ntruffle cp file.txt server:/tmp/  # copy files (SHA-256 verified)\ntruffle tcp server:5432           # raw TCP (like netcat)\ntruffle doctor                    # diagnose connectivity\ntruffle down                      # graceful shutdown\ntruffle update                    # self-update to latest release\n```\n\n### Agent-Friendly Streaming\n\n```bash\ntruffle watch --json              # stream mesh events as JSONL\ntruffle wait server --timeout 60  # block until peer comes online\ntruffle recv --json --from server # block for next message\n```\n\nAll commands support `--json` for structured output with versioned envelopes.\n\n## Features\n\n- **Interactive TUI** — Claude Code-inspired terminal UI with live activity feed, device panel, slash commands, file picker, autocomplete\n- **Chat messaging** — send/broadcast with `@device` mentions, message grouping for consecutive messages\n- **File transfer** — SHA-256 verified, progress bars, interactive accept/reject modal, streaming to disk (constant memory)\n- **Peer discovery** — automatic via Tailscale WatchIPNBus, ~30s offline detection\n- **Smart naming** — auto-generates clean device names from OS hostname (`Jamess-MBP-6.ts.net lan` → `jamess-mbp`)\n- **Agent mode** — `--json` on all commands, structured exit codes, `NO_COLOR`, `truffle watch/wait/recv` for scripting\n- **Cross-platform** — macOS, Linux (musl static), Windows\n- **First-run onboarding** — name picker + Tailscale auth wizard\n\n## Architecture\n\nLayered architecture (RFC 012) with file transfer as a first-class core feature (RFC 014):\n\n```\nLayer 7: Applications   ── CLI commands, TUI, daemon handler\n         Node API       ── 16-method public API + FileTransfer manager\nLayer 6: Envelope       ── namespace-routed message framing (JSON codec)\nLayer 5: Session        ── PeerRegistry, lazy WS connections, event broadcast\nLayer 4: Transport      ── WebSocket, TCP, UDP, QUIC transports\nLayer 3: Network        ── TailscaleProvider (peer discovery via WatchIPNBus)\n         Go Sidecar     ── tsnet integration, WireGuard tunnels\n```\n\n**Key design principles:**\n- **Layer 3 is the source of truth for peers** — peers exist because Tailscale reports them, not because of transport connections\n- **Lazy connections** — WebSocket connections are established on first `send()`, not eagerly\n- **Layer separation** — each layer has a trait boundary; e.g., `NetworkProvider` can be swapped without touching upper layers\n- **File transfer uses Node primitives** — signaling over WS namespace `\"ft\"`, data over raw TCP, no special infrastructure\n\n### File Transfer (RFC 014)\n\nThe `file_transfer` module in `truffle-core` provides:\n\n```rust\nlet ft = node.file_transfer();\n\n// Send a file\nft.send_file(\"peer-id\", \"/path/to/file.txt\", \"/dest/\").await?;\n\n// Pull a file from a remote peer\nft.pull_file(\"peer-id\", \"/remote/file.txt\", \"/local/path.txt\").await?;\n\n// Receive with interactive accept/reject\nlet mut offers = ft.offer_channel(node.clone()).await;\nwhile let Some((offer, responder)) = offers.recv().await {\n    responder.accept(\"/save/path\");  // or responder.reject(\"reason\")\n}\n\n// Or auto-accept everything\nft.auto_accept(node.clone(), \"~/Downloads/truffle/\").await;\n\n// Subscribe to transfer lifecycle events\nlet mut events = ft.subscribe();\n```\n\n## Crates \u0026 Packages\n\n| Crate / Package | Status | Description |\n|-----------------|--------|-------------|\n| [`truffle-core`](crates/truffle-core) | **Active** | Rust library — Layers 3-6, Node API, file transfer (~12k LOC) |\n| [`truffle-cli`](crates/truffle-cli) | **Active** | CLI + TUI — 13 one-shot commands, interactive terminal UI (~10k LOC) |\n| [`sidecar-slim`](packages/sidecar-slim/) | **Active** | Go sidecar — tsnet, WatchIPNBus, TCP bridge (~1.9k LOC) |\n| [`truffle-napi`](crates/truffle-napi) | Bindings | NAPI-RS native addon for Node.js (rewritten in RFC 015) |\n| [`truffle-tauri-plugin`](crates/truffle-tauri-plugin) | Bindings | Tauri v2 plugin for desktop apps (rewritten in RFC 015) |\n\n**npm:** `@vibecook/truffle` + platform-specific sidecar packages\n\n## Development\n\n```bash\ncargo build --workspace       # build all Rust crates\ncargo test --workspace        # run tests (~187 tests)\n```\n\n### Prerequisites\n\n- **Rust** \u003e= 1.86\n- **Go** \u003e= 1.22 (for building the sidecar)\n- **Tailscale** installed and authenticated\n\n## RFCs\n\n| RFC | Status | Description |\n|-----|--------|-------------|\n| [RFC 012](docs/rfcs/012-layered-architecture-redesign.md) | Implemented | Clean layered architecture redesign |\n| [RFC 013](docs/rfcs/013-tui-redesign.md) | Implemented | Dual-mode TUI + agent CLI redesign |\n| [RFC 014](docs/rfcs/014-file-transfer-core.md) | Implemented | File transfer as core feature with accept/reject API |\n| [RFC 015](docs/rfcs/015-binding-rewrite.md) | Implemented | NAPI-RS and Tauri plugin rewrite |\n\n## Documentation\n\n- [GitHub Pages](https://jamesyong-42.github.io/truffle/) — install scripts and docs\n- [Getting Started](docs/guide/getting-started.md)\n- [CLI Reference](docs/guide/cli.md)\n- [Architecture](docs/guide/architecture.md)\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesyong-42%2Ftruffle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjamesyong-42%2Ftruffle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjamesyong-42%2Ftruffle/lists"}