README
¶
waired-agent
Client-side source of Waired: the waired CLI, the
waired-agent daemon (mesh networking, NAT traversal, local inference
routing), the desktop tray, installers/packaging, and the shared
protocol module github.com/waired-ai/waired-agent/proto that the
control plane imports.
User documentation: https://docs.waired.ai/ (authored under
docs-site/ in this repo).
Install
# Linux / macOS
curl -fsSL https://github.com/waired-ai/waired-agent/releases/latest/download/install.sh | sh
# Windows
iwr -useb https://github.com/waired-ai/waired-agent/releases/latest/download/install.ps1 | iex
Edge channel (latest main build, unstable)
Rebuilt on every merge to main — not for production use.
# Linux / macOS
curl -fsSL https://github.com/waired-ai/waired-agent/releases/latest/download/install.sh | sh -s -- --edge
# Windows
$env:WAIRED_VERSION = 'edge'
iwr -useb https://github.com/waired-ai/waired-agent/releases/latest/download/install.ps1 | iex
Once on edge, waired update stays on edge; switch channels with
waired update --edge / --stable.
Uninstall
Removes the binaries, unregisters the service, and (best-effort)
deregisters the device from your account. Local config/state is kept;
add --clean / -Clean for a full wipe.
# Linux / macOS
curl -fsSL https://github.com/waired-ai/waired-agent/releases/latest/download/uninstall.sh | sh
# Windows
iwr -useb https://github.com/waired-ai/waired-agent/releases/latest/download/uninstall.ps1 | iex
Details and all installer flags: docs.waired.ai
and packaging/install/README.md.
Layout
cmd/waired CLI
cmd/waired-agent agent daemon
cmd/waired-tray desktop tray
cmd/catalog-tool model-catalog tooling
internal/ agent implementation (not importable cross-module)
proto/ shared protocol Go module (imported by the CP)
packaging/ install.sh / install.ps1, nfpm, systemd, Inno Setup
scripts/ install helpers, CI guards, dev install-test harnesses
docs-site/ public user documentation (docs.waired.ai)
Build / test
go build ./... && go vet ./...
go test ./...
(cd proto && go test ./...)
make build-agent build-tray # linux/amd64 into ./bin/
make verify-cross # GOOS={linux,windows,darwin} go vet
Protocol changes (public-first)
- Revise
proto/here, land the change. - Tag
proto/vX.Y.Z. - Bump the module in the private control-plane repo.
Release tags: v* = agent/installer releases (stable channel);
proto/v* = protocol module versions. The two never overlap.
Contributing
External issues and pull requests are welcome and reviewed on a
best-effort basis — see CONTRIBUTING.md. Every
commit must carry a DCO Signed-off-by trailer (git commit -s).
Security reports go through SECURITY.md, not public
issues.
License
Apache-2.0 — see LICENSE. Release artifacts bundle the
third-party license notices as THIRD_PARTY_LICENSES.
Waired uses the WireGuard® protocol via wireguard-go. "WireGuard" and the "WireGuard" logo are registered trademarks of Jason A. Donenfeld; Waired is not sponsored or endorsed by the WireGuard project. Ollama, vLLM, Claude Code, and OpenCode are trademarks of their respective owners; Waired integrates with them but is not affiliated with or endorsed by their vendors.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
catalog-tool
command
Command catalog-tool is the deterministic helper behind the model-catalog refresh pipeline (issue #413).
|
Command catalog-tool is the deterministic helper behind the model-catalog refresh pipeline (issue #413). |
|
waired
command
Command waired is the Waired CLI.
|
Command waired is the Waired CLI. |
|
waired-agent
command
Depth-aware long-context benchmark (#624).
|
Depth-aware long-context benchmark (#624). |
|
waired-tray
command
Command waired-tray is the Waired desktop tray.
|
Command waired-tray is the Waired desktop tray. |
|
internal
|
|
|
agentconfig
Package agentconfig holds the agent-side runtime configuration for the inference subsystem (and, in the future, other subsystems).
|
Package agentconfig holds the agent-side runtime configuration for the inference subsystem (and, in the future, other subsystems). |
|
buildflag
Package buildflag is the single source of truth for compile-time feature gating between the default (dev) build and the hardened production build (`-tags prod`).
|
Package buildflag is the single source of truth for compile-time feature gating between the default (dev) build and the hardened production build (`-tags prod`). |
|
buildinfo
Package buildinfo exposes the binary's build-time version and commit, stamped via the linker (-ldflags -X).
|
Package buildinfo exposes the binary's build-time version and commit, stamped via the linker (-ldflags -X). |
|
catalog
Package catalog manages model manifests and the local cache state.
|
Package catalog manages model manifests and the local cache state. |
|
catalog/discovery
Package discovery is the pure (no-I/O) filter + diff logic of the catalog radar: given a list of Hugging Face models and the current catalog/seen state, it decides which are fresh candidates worth researching.
|
Package discovery is the pure (no-I/O) filter + diff logic of the catalog radar: given a list of Hugging Face models and the current catalog/seen state, it decides which are fresh candidates worth researching. |
|
catalog/hfclient
Package hfclient is a small read-only HTTP client for the public Hugging Face Hub API.
|
Package hfclient is a small read-only HTTP client for the public Hugging Face Hub API. |
|
catalog/scoring
Package scoring encodes the deterministic model-footprint formulas used to author bundled catalog manifests: weight size, KV-cache footprint, decode FLOPs, and the quality_tier composite.
|
Package scoring encodes the deterministic model-footprint formulas used to author bundled catalog manifests: weight size, KV-cache footprint, decode FLOPs, and the quality_tier composite. |
|
controlclient
Package controlclient implements the agent-side HTTP client for the Waired Control Plane.
|
Package controlclient implements the agent-side HTTP client for the Waired Control Plane. |
|
deauth
Package deauth holds the single best-effort "tell the Control Plane this device is going away" routine, shared by every surface that needs it: `waired logout` (CLI), `waired-agent uninstall` (service teardown on Windows / macOS / Linux) and — via the CLI — the Debian package prerm.
|
Package deauth holds the single best-effort "tell the Control Plane this device is going away" routine, shared by every surface that needs it: `waired logout` (CLI), `waired-agent uninstall` (service teardown on Windows / macOS / Linux) and — via the CLI — the Debian package prerm. |
|
devicekeys
Package devicekeys generates and persists the two key types each Waired device needs:
|
Package devicekeys generates and persists the two key types each Waired device needs: |
|
download
Package download wraps the per-runtime model download tools so the rest of waired-agent can drive them through a uniform Pull / state machine.
|
Package download wraps the per-runtime model download tools so the rest of waired-agent can drive them through a uniform Pull / state machine. |
|
gateway
Package gateway hosts the Local Gateway HTTP server (port 9473 by default), which exposes OpenAI- and Anthropic-compatible chat APIs to local clients (Claude Code, Open Code, curl, …) and proxies them — via the router and runtime adapters — to the appropriate backend engine.
|
Package gateway hosts the Local Gateway HTTP server (port 9473 by default), which exposes OpenAI- and Anthropic-compatible chat APIs to local clients (Claude Code, Open Code, curl, …) and proxies them — via the router and runtime adapters — to the appropriate backend engine. |
|
gcptoken
Package gcptoken provides an http.RoundTripper that injects a Google identity token (audience pinned at construction time) into the Authorization header.
|
Package gcptoken provides an http.RoundTripper that injects a Google identity token (audience pinned at construction time) into the Authorization header. |
|
gui/tray
Package tray builds the Waired desktop tray UI on top of fyne.io/systray.
|
Package tray builds the Waired desktop tray UI on top of fyne.io/systray. |
|
hardware
Package hardware detects local machine capabilities relevant to running LLM runtimes: OS / arch / CPU / RAM / GPU / installed engines.
|
Package hardware detects local machine capabilities relevant to running LLM runtimes: OS / arch / CPU / RAM / GPU / installed engines. |
|
identity
Package identity manages the on-disk state a Waired agent needs to keep across restarts: the result of `waired init` (account / network / device IDs, control plane URL, signing key fingerprint) plus the secret artifacts (Machine Key, Node Key, Device Access Token, cached Device Certificate, cached Network Map).
|
Package identity manages the on-disk state a Waired agent needs to keep across restarts: the result of `waired init` (account / network / device IDs, control plane URL, signing key fingerprint) plus the secret artifacts (Machine Key, Node Key, Device Access Token, cached Device Certificate, cached Network Map). |
|
inference
Package inference exposes the overlay-side HTTP service that remote peers reach over the WireGuard data plane.
|
Package inference exposes the overlay-side HTTP service that remote peers reach over the WireGuard data plane. |
|
inferencemesh
Package inferencemesh implements the agent-side aggregator that fuses (a) this device's local engine probe and (b) every peer's pushed InferenceState (received via the network map) into a single in-memory mesh snapshot.
|
Package inferencemesh implements the agent-side aggregator that fuses (a) this device's local engine probe and (b) every peer's pushed InferenceState (received via the network map) into a single in-memory mesh snapshot. |
|
integration
Package integration owns the auto-configuration of third-party coding agents (Claude Code, OpenCode, ...) so they route their requests through the local Waired Gateway at 127.0.0.1:9473.
|
Package integration owns the auto-configuration of third-party coding agents (Claude Code, OpenCode, ...) so they route their requests through the local Waired Gateway at 127.0.0.1:9473. |
|
integration/claudecode
Package claudecode implements the Adapter for Claude Code.
|
Package claudecode implements the Adapter for Claude Code. |
|
integration/claudemanaged
Package claudemanaged writes Claude Code "managed settings" so the local waired agent can route Claude Code at its loopback gateway without any MITM proxy, CA, /etc/hosts edit, or shell-env management (#488).
|
Package claudemanaged writes Claude Code "managed settings" so the local waired agent can route Claude Code at its loopback gateway without any MITM proxy, CA, /etc/hosts edit, or shell-env management (#488). |
|
integration/detect
Package detect inspects the user's shells and IDEs for an existing `waired claude` wrapper configuration, reporting (per location) whether the configuration is present and whether it points at the currently-running waired binary.
|
Package detect inspects the user's shells and IDEs for an existing `waired claude` wrapper configuration, reporting (per location) whether the configuration is present and whether it points at the currently-running waired binary. |
|
integration/openclaw
Package openclaw implements the Adapter for OpenClaw (openclaw/openclaw — a Node/TypeScript AI assistant CLI).
|
Package openclaw implements the Adapter for OpenClaw (openclaw/openclaw — a Node/TypeScript AI assistant CLI). |
|
integration/opencode
Package opencode implements the Adapter for OpenCode.
|
Package opencode implements the Adapter for OpenCode. |
|
integration/shellalias
Package shellalias hosts the sentinel constants and rc-file inventory shared between the installer (`waired link`) and the detector (`internal/integration/detect`).
|
Package shellalias hosts the sentinel constants and rc-file inventory shared between the installer (`waired link`) and the detector (`internal/integration/detect`). |
|
integration/vscode
Package vscode is the migration-scrub remnant of the old VSCode-family Claude Code wrapper integration.
|
Package vscode is the migration-scrub remnant of the old VSCode-family Claude Code wrapper integration. |
|
management
Package management implements the localhost-only HTTP API that the waired CLI talks to.
|
Package management implements the localhost-only HTTP API that the waired CLI talks to. |
|
management/observabilityclient
Package observabilityclient is the shared 1-shot HTTP client for the agent-local /waired/v1/observability/{state,events} endpoints exposed by Phase 9 (PR #67).
|
Package observabilityclient is the shared 1-shot HTTP client for the agent-local /waired/v1/observability/{state,events} endpoints exposed by Phase 9 (PR #67). |
|
network/disco
Package disco implements the agent-side NAT-traversal subsystem: STUN-like endpoint observation against relays, peer↔peer probe/pong, and NAT-type detection.
|
Package disco implements the agent-side NAT-traversal subsystem: STUN-like endpoint observation against relays, peer↔peer probe/pong, and NAT-type detection. |
|
network/netif
Package netif enumerates the host's reachable network interface addresses and emits them as AdvertiseEndpoints candidates so the control plane can hand them to peers.
|
Package netif enumerates the host's reachable network interface addresses and emits them as AdvertiseEndpoints candidates so the control plane can hand them to peers. |
|
network/wgnet
Package wgnet wraps wireguard-go's userspace device and netstack TUN so the rest of waired can dial and listen on the overlay without touching the host kernel routing table.
|
Package wgnet wraps wireguard-go's userspace device and netstack TUN so the rest of waired can dial and listen on the overlay without touching the host kernel routing table. |
|
observability
Package observability provides the agent-local telemetry surface consumed by tray / claude plugin / Grafana scrapers via the management API.
|
Package observability provides the agent-local telemetry surface consumed by tray / claude plugin / Grafana scrapers via the management API. |
|
platform/autostart
Package autostart owns the per-user "start on login" registration for the waired-tray.
|
Package autostart owns the per-user "start on login" registration for the waired-tray. |
|
platform/browser
Package browser opens a URL in the user's default web browser and reports whether the current session can plausibly show one.
|
Package browser opens a URL in the user's default web browser and reports whether the current session can plausibly show one. |
|
platform/elevation
Package elevation reports whether the current process is running with elevated privileges — root on Unix, an elevated (high-integrity) token on Windows.
|
Package elevation reports whether the current process is running with elevated privileges — root on Unix, an elevated (high-integrity) token on Windows. |
|
platform/keychain
Package keychain provides opt-in access to the macOS Keychain for callers that want at-rest encryption stronger than POSIX 0o600 file mode.
|
Package keychain provides opt-in access to the macOS Keychain for callers that want at-rest encryption stronger than POSIX 0o600 file mode. |
|
platform/logsink
Package logsink wraps a primary slog.Handler with an OS-native secondary sink for high-severity records.
|
Package logsink wraps a primary slog.Handler with an OS-native secondary sink for high-severity records. |
|
platform/notification
Package notification surfaces short, transient OS-level toast notifications.
|
Package notification surfaces short, transient OS-level toast notifications. |
|
platform/paths
Package paths is the single source of truth for resolving the waired agent's on-disk state directory and its conventional subdirectories (secrets/, cache/) across Linux, Windows, and macOS.
|
Package paths is the single source of truth for resolving the waired agent's on-disk state directory and its conventional subdirectories (secrets/, cache/) across Linux, Windows, and macOS. |
|
platform/proclist
Package proclist enumerates the local process table with each process's full argv, so the agent can read a live model runner's actual flags — specifically the Ollama-spawned llama-server / `ollama runner` and its -np (num parallel) and -c (context) values, which /api/ps does not expose (waired#763).
|
Package proclist enumerates the local process table with each process's full argv, so the agent can read a live model runner's actual flags — specifically the Ollama-spawned llama-server / `ollama runner` and its -np (num parallel) and -c (context) values, which /api/ps does not expose (waired#763). |
|
platform/sdsocket
Package sdsocket reads listeners passed by a socket-activating service manager (systemd on Linux; launchd uses a different API and is handled elsewhere) via the sd_listen_fds protocol:
|
Package sdsocket reads listeners passed by a socket-activating service manager (systemd on Linux; launchd uses a different API and is handled elsewhere) via the sd_listen_fds protocol: |
|
platform/secrets
Package secrets owns the on-disk protection model for the waired agent's sensitive state (private keys, access tokens, gateway tokens, inference state, preferences).
|
Package secrets owns the on-disk protection model for the waired agent's sensitive state (private keys, access tokens, gateway tokens, inference state, preferences). |
|
platform/securestore
Package securestore composes the opt-in macOS Keychain (internal/platform/keychain) with the file-based secret store (internal/platform/secrets) so at-rest secret callsites can prefer the Keychain on darwin while transparently falling back to a 0600 file on every other platform.
|
Package securestore composes the opt-in macOS Keychain (internal/platform/keychain) with the file-based secret store (internal/platform/secrets) so at-rest secret callsites can prefer the Keychain on darwin while transparently falling back to a 0600 file on every other platform. |
|
platform/service
Package service is the OS-portable interface to the platform's service manager: SCM on Windows, systemd on Linux, launchd (stub only) on macOS.
|
Package service is the OS-portable interface to the platform's service manager: SCM on Windows, systemd on Linux, launchd (stub only) on macOS. |
|
platform/trayhost
Package trayhost reports whether the current desktop session can render a StatusNotifierItem (SNI) system-tray icon — the protocol waired-tray speaks via fyne.io/systray on Linux.
|
Package trayhost reports whether the current desktop session can render a StatusNotifierItem (SNI) system-tray icon — the protocol waired-tray speaks via fyne.io/systray on Linux. |
|
proxy/hostsfile
Package hostsfile manages a marker-delimited block in the OS hosts file that redirects the intercepted hostnames (e.g.
|
Package hostsfile manages a marker-delimited block in the OS hosts file that redirects the intercepted hostnames (e.g. |
|
proxy/intercept
Package intercept implements the plain-HTTP loopback proxy that Claude Code talks to via the managed-settings `ANTHROPIC_BASE_URL`.
|
Package intercept implements the plain-HTTP loopback proxy that Claude Code talks to via the managed-settings `ANTHROPIC_BASE_URL`. |
|
proxy/legacycleanup
Package legacycleanup removes the artifacts of the retired transparent MITM Claude proxy (#488) when a host is upgraded to the managed-settings ANTHROPIC_BASE_URL integration.
|
Package legacycleanup removes the artifacts of the retired transparent MITM Claude proxy (#488) when a host is upgraded to the managed-settings ANTHROPIC_BASE_URL integration. |
|
proxy/trust
Package trust REMOVES the artifacts of the retired transparent-proxy MITM root CA: the CA anchored in the OS trust store and the NODE_EXTRA_CA_CERTS bridge that Claude Code (a Node app, which ignores the OS trust store) used to trust the minted leaves.
|
Package trust REMOVES the artifacts of the retired transparent-proxy MITM root CA: the CA anchored in the OS trust store and the NODE_EXTRA_CA_CERTS bridge that Claude Code (a Node app, which ignores the OS trust store) used to trust the minted leaves. |
|
relay/client
Package client implements the agent-side relay session for the waired-relay-v1 subprotocol.
|
Package client implements the agent-side relay session for the waired-relay-v1 subprotocol. |
|
router
#624: the ~200k coding-agent context floor.
|
#624: the ~200k coding-agent context floor. |
|
runtime
Package runtime owns engine adapters: code that knows how to start, stop, health-check, and HTTP-proxy a backend LLM runtime (Ollama in Phase A; vLLM in Phase B).
|
Package runtime owns engine adapters: code that knows how to start, stop, health-check, and HTTP-proxy a backend LLM runtime (Ollama in Phase A; vLLM in Phase B). |
|
runtime/codeui
Package codeui vendors and supervises the bundled OpenCode coding-agent web UI (#429).
|
Package codeui vendors and supervises the bundled OpenCode coding-agent web UI (#429). |
|
runtime/openaicompat
Package openaicompat is the runtime.Adapter for an external OpenAI- compatible HTTP endpoint that the agent does NOT own (no subprocess lifecycle).
|
Package openaicompat is the runtime.Adapter for an external OpenAI- compatible HTTP endpoint that the agent does NOT own (no subprocess lifecycle). |
|
runtime/peer
Package peer implements runtime.Adapter for inference engines that live on a *peer* in the WireGuard mesh — i.e., another waired-agent reachable via overlay IP.
|
Package peer implements runtime.Adapter for inference engines that live on a *peer* in the WireGuard mesh — i.e., another waired-agent reachable via overlay IP. |
|
runtime/state
Package state owns the runtime-state files the agent writes and the CLI / shell-rc reads.
|
Package state owns the runtime-state files the agent writes and the CLI / shell-rc reads. |
|
setup
Package setup is the orchestrator behind `waired init` and the shared targets `waired link` / `waired deploy` re-run individually.
|
Package setup is the orchestrator behind `waired init` and the shared targets `waired link` / `waired deploy` re-run individually. |
|
testharness
Package testharness provides the agent-side dispatcher for test directives carried in the signed Network Map.
|
Package testharness provides the agent-side dispatcher for test directives carried in the signed Network Map. |
|
update
Package update resolves the latest published waired release and compares it against the running build, powering the manual update path (#293).
|
Package update resolves the latest published waired release and compares it against the running build, powering the manual update path (#293). |
|
version
Package version provides dependency-free comparison of dotted-numeric version strings (X.Y.Z).
|
Package version provides dependency-free comparison of dotted-numeric version strings (X.Y.Z). |
|
proto
module
|
|
|
scripts
|
|
|
dev/hwprobe
command
Command hwprobe runs the agent's hardware profiler once and prints the JSON result.
|
Command hwprobe runs the agent's hardware profiler once and prints the JSON result. |
|
dev/mock-mgmt
command
Command mock-mgmt stands in for the agent's Local Management API for the limited purpose of driving the desktop tray during darwin UI screenshot verification.
|
Command mock-mgmt stands in for the agent's Local Management API for the limited purpose of driving the desktop tray during darwin UI screenshot verification. |
|
install
Package installscripts embeds the OS installer scripts that live in scripts/install/ so compiled binaries (e.g.
|
Package installscripts embeds the OS installer scripts that live in scripts/install/ so compiled binaries (e.g. |
Click to show internal directories.
Click to hide internal directories.