outpost

module
v0.14.21 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 29, 2026 License: MIT

README

outpost

The home-host agent for ai.dhnt.io — one binary per machine you want to surface through the portal. It registers with a one-time code, dials back over a secure tunnel, and serves your local apps (HTTP, shell, desktop, clipboard) so authenticated portal users reach them at https://ai.dhnt.io/h/<host>/app/<name>/. The HTTP server binds loopback only; the portal is the sole ingress.

Fully open source under the MIT license — nothing is hidden, nothing phones home. The wire protocol is documented inline in internal/agent/portal/ (exchange.go is the only handshake); a self-built outpost pairs with the public portal exactly like an official binary.

Install

macOS / Linux — one-line installer (downloads the matching release binary, verifies sha256, optionally registers launchd / systemd):

curl -fsSL https://raw.githubusercontent.com/qiangli/outpost/main/scripts/install.sh | sh

Windows — PowerShell installer (Invoke-WebRequest avoids Mark-of-the-Web, so SmartScreen does not gate first run):

iwr -useb https://raw.githubusercontent.com/qiangli/outpost/main/scripts/install.ps1 | iex

Environment overrides (INSTALL_DIR, OUTPOST_VERSION, NO_SERVICE), Linux PAM auth, Windows Defender notes, and uninstall: docs/install.md (outpost docs install).

Pair with the portal

  1. Sign in at https://ai.dhnt.io/admin/ → Hosts → Generate invite code.

  2. On the home machine:

    outpost register --server https://ai.dhnt.io --code <one-time-code> --name laptop
outpost start

register exchanges the code for the agent's persistent config; outpost start dials in and serves the local apps. Declare apps with MATRIX_APPS="ycode=http://127.0.0.1:8765,jupyter=http://127.0.0.1:8888" (ycode at :8765 is the default). Full flow: docs/pairing.md.

What outpost serves

  • /app/<name>/* — reverse-proxy for any HTTP app declared in MATRIX_APPS
  • /shell — admin-tier PTY shell (WebSocket) · /desktop — VNC relay · /clipboard — clipboard bridge
  • /auth — credential check against the host OS (or a custom --auth-url)

All reached only through the portal — the HTTP server binds 127.0.0.1:<random>.

Build from source

Requires Go 1.25+. go install …@latest does not work — go.mod carries a sibling-path replace for the forked shell runner, which the build scripts materialize for you.

git clone https://github.com/qiangli/outpost && cd outpost
./scripts/build.sh                 # macOS / Linux → ./bin/outpost
# Windows: powershell -ExecutionPolicy Bypass -File .\scripts\build.ps1

Already have any outpost release? outpost build does the whole flow — clone, sibling bootstrap, build — with only the Go toolchain (no system git / make / bash). Pin with outpost build --ref v0.3.0 (tag or sha), then outpost upgrade --local <built>. All build paths, pinning, and cross-compile: docs/building.md (outpost docs building).

Testing a release build (QA)

A QA host verifies a published build (no source, no Go — bashy only, which self-provisions git / coreutils) via the qa task in dag.md:

OUTPOST_TEST_VERSION=v1.2.3-dev bashy dag dag.md qa

It downloads this host's OS/arch artifact, verifies sha256, and runs a runtime smoke — the same probe the upgrade worker runs before swapping a live binary. Standing-poller setup: docs/qa-poller-host-setup.md.

Docs

Agents working in this repo (with a local bashy kb): bashy kb show outpost-orientation for the operational map; never-pkill-on-an-outpost-host and outpost-upgrade-local-no-ops-on-same-commit-rebuilds for the sharp edges.

PRs welcome.

Directories

Path Synopsis
cmd
outpost command
`outpost connect <host>` is the CLI mirror of the Periscope launcher's "Connect" button: it runs the once-per-idle-window OS-password step that unlocks the host for subsequent SSH connections.
 `outpost connect <host>` is the CLI mirror of the Periscope launcher's "Connect" button: it runs the once-per-idle-window OS-password step that unlocks the host for subsequent SSH connections.
outpost-vk command
Command outpost-vk is a standalone proof-of-concept runner for the vkpodman provider.
 Command outpost-vk is a standalone proof-of-concept runner for the vkpodman provider.
internal
agent
Package agent runs on the home host, dials cloudbox over the matrix tunnel, and exposes local apps (ycode, shell, desktop, plus user-defined LAN services).
 Package agent runs on the home host, dials cloudbox over the matrix tunnel, and exposes local apps (ycode, shell, desktop, plus user-defined LAN services).
agent/admincore
Package admincore holds the protocol-agnostic configuration operations outpost exposes — pairing, app CRUD, outbound mounts, built-in toggles, cluster kubeconfig, restart.
 Package admincore holds the protocol-agnostic configuration operations outpost exposes — pairing, app CRUD, outbound mounts, built-in toggles, cluster kubeconfig, restart.
agent/adminui
Package adminui serves the local-only configuration web UI for outpost.
 Package adminui serves the local-only configuration web UI for outpost.
agent/apphealth
Package apphealth provides per-app reachability measurement over outpost-owned TCP/HTTP paths (no ICMP/raw sockets).
 Package apphealth provides per-app reachability measurement over outpost-owned TCP/HTTP paths (no ICMP/raw sockets).
agent/backup
Package backup is the outpost-side, app-opaque folder watcher that produces backup candidates on a cron schedule.
 Package backup is the outpost-side, app-opaque folder watcher that produces backup candidates on a cron schedule.
agent/brain
Package brain is cloudbox/outpost/bashy's built-in decision-maker — the faculty that lets the platform DECIDE, not just execute, for any operation that needs judgment.
 Package brain is cloudbox/outpost/bashy's built-in decision-maker — the faculty that lets the platform DECIDE, not just execute, for any operation that needs judgment.
agent/certs
agent/clusterllm
Package clusterllm is outpost's passive integrator for an intra-home distributed-inference backend — a runtime that tensor/pipeline-splits a single model across several member machines so a home can serve a model too large for any one box.
 Package clusterllm is outpost's passive integrator for an intra-home distributed-inference backend — a runtime that tensor/pipeline-splits a single model across several member machines so a home can serve a model too large for any one box.
agent/conf
Package conf holds the matrix-agent runtime configuration.
 Package conf holds the matrix-agent runtime configuration.
agent/discovery
mDNS advertisement: register ourselves on `_outpost._tcp.local`.
 mDNS advertisement: register ourselves on `_outpost._tcp.local`.
agent/fleetreg
Package fleetreg pushes this host's fleet inventory — the tools, agents, and skills it has installed — up to cloudbox.
 Package fleetreg pushes this host's fleet inventory — the tools, agents, and skills it has installed — up to cloudbox.
agent/heartbeat
Package heartbeat owns the outpost → cloudbox active liveness push (Layer-5 defense).
 Package heartbeat owns the outpost → cloudbox active liveness push (Layer-5 defense).
agent/hostauth
Package hostauth verifies the host OS's own credentials.
 Package hostauth verifies the host OS's own credentials.
agent/localsock
Package localsock is the one place outpost decides how to reach a local daemon endpoint that is not a TCP port: a unix-domain socket or a Windows named pipe.
 Package localsock is the one place outpost decides how to reach a local daemon endpoint that is not a TCP port: a unix-domain socket or a Windows named pipe.
agent/mcpapi
Package mcpapi exposes outpost's configuration surface to agent tools (Claude Code, Windsurf, the outpost CLI, ...) over the Model Context Protocol.
 Package mcpapi exposes outpost's configuration surface to agent tools (Claude Code, Windsurf, the outpost CLI, ...) over the Model Context Protocol.
agent/mesh
Package mesh is the outpost's libp2p peer data plane — the node that carries authenticated, encrypted, NAT-traversing peer↔peer streams.
 Package mesh is the outpost's libp2p peer data plane — the node that carries authenticated, encrypted, NAT-traversing peer↔peer streams.
agent/mirror
Package mirror supervises mobility-aware continuous directory mirrors.
 Package mirror supervises mobility-aware continuous directory mirrors.
agent/ollama
Package ollama owns the outpost-side of the LLM pool: it watches the local Ollama daemon's model inventory, publishes the inventory to cloudbox so the pool scheduler can route by model presence, and tracks in-flight request counts so cloudbox can avoid over-scheduling a host with limited GPU capacity.
 Package ollama owns the outpost-side of the LLM pool: it watches the local Ollama daemon's model inventory, publishes the inventory to cloudbox so the pool scheduler can route by model presence, and tracks in-flight request counts so cloudbox can avoid over-scheduling a host with limited GPU capacity.
agent/osversion
Package osversion returns a one-line human-readable OS version label for the running host, e.g.
 Package osversion returns a one-line human-readable OS version label for the running host, e.g.
agent/otel
Package otel discovers the local `ycode serve` observability stack (Prometheus + Alertmanager + VictoriaLogs + Jaeger + Perses, all reverse-proxied under one bearer-authed HTTP server) and lets outpost expose each surface through the matrix tunnel as a built-in app.
 Package otel discovers the local `ycode serve` observability stack (Prometheus + Alertmanager + VictoriaLogs + Jaeger + Perses, all reverse-proxied under one bearer-authed HTTP server) and lets outpost expose each surface through the matrix tunnel as a built-in app.
agent/overlaykey
Package overlaykey fetches a fresh single-use overlay (Tailscale/ Headscale) pre-auth key from cloudbox when this host's tailnet registration is no longer valid.
 Package overlaykey fetches a fresh single-use overlay (Tailscale/ Headscale) pre-auth key from cloudbox when this host's tailnet registration is no longer valid.
agent/peerhosts
Package peerhosts caches the list of paired outpost hostnames as returned by cloudbox's /api/v1/ssh/hosts endpoint.
 Package peerhosts caches the list of paired outpost hostnames as returned by cloudbox's /api/v1/ssh/hosts endpoint.
agent/peerplane
Package peerplane is the outpost side of the dhnt p2p resource fabric's peer data plane.
 Package peerplane is the outpost side of the dhnt p2p resource fabric's peer data plane.
agent/peerstatus
Package peerstatus is a thin client for cloudbox's GET /api/v1/peers — the peer status board.
 Package peerstatus is a thin client for cloudbox's GET /api/v1/peers — the peer status board.
agent/peerticket
Package peerticket verifies short-lived JWTs ("peer tickets") cloudbox issues at `POST /api/v1/ssh/peer-ticket`.
 Package peerticket verifies short-lived JWTs ("peer tickets") cloudbox issues at `POST /api/v1/ssh/peer-ticket`.
agent/portal
Package portal speaks to the cloud portal's pairing endpoint (POST /api/register/exchange).
 Package portal speaks to the cloud portal's pairing endpoint (POST /api/register/exchange).
agent/recipebuilder
Package recipebuilder is the per-node half of the DKS "recipes, not blobs" image-distribution model (dhnt/docs/dks-image-recipe-distribution-design.md).
 Package recipebuilder is the per-node half of the DKS "recipes, not blobs" image-distribution model (dhnt/docs/dks-image-recipe-distribution-design.md).
agent/repair
Package repair provides the POST /admin/repair receiver — the cloudbox-driven trigger that starts a CI-failure self-fix on this host.
 Package repair provides the POST /admin/repair receiver — the cloudbox-driven trigger that starts a CI-failure self-fix on this host.
agent/runtime
Package runtime supervises a podman container that hosts this outpost's k3s-agent kubelet.
 Package runtime supervises a podman container that hosts this outpost's k3s-agent kubelet.
agent/runtime/image/cni command
Command outpost-cni implements a minimal Container Network Interface (CNI) plugin for Phase 3 of the outpost overlay design.
 Command outpost-cni implements a minimal Container Network Interface (CNI) plugin for Phase 3 of the outpost overlay design.
agent/runtime/image/cni/internal/plugin
Package plugin contains the load-bearing logic for the outpost-cni binary, factored out so the tiny main package stays under 100 lines.
 Package plugin contains the load-bearing logic for the outpost-cni binary, factored out so the tiny main package stays under 100 lines.
agent/sandbox
Package sandbox implements outpost's safe-by-default container "sandbox" provider: a filtered libpod/docker API proxy that strips the escape-bearing knobs (privileged, host namespaces, host bind-mounts, added capabilities, devices) and injects per-request resource caps, so a remote caller who clears the cloudbox elevation gate can run containers without getting root-equivalent control of the host.
 Package sandbox implements outpost's safe-by-default container "sandbox" provider: a filtered libpod/docker API proxy that strips the escape-bearing knobs (privileged, host namespaces, host bind-mounts, added capabilities, devices) and injects per-request resource caps, so a remote caller who clears the cloudbox elevation gate can run containers without getting root-equivalent control of the host.
agent/selfcheck
Package selfcheck owns the Layer-2 defense: detect partial outpost corruption and self-heal from durable inputs.
 Package selfcheck owns the Layer-2 defense: detect partial outpost corruption and self-heal from durable inputs.
agent/shard
Package shard orchestrates a Prima.cpp pipelined-ring shard over the mesh forwarder: serving a model bigger than any single node by splitting its layers across paired mesh peers.
 Package shard orchestrates a Prima.cpp pipelined-ring shard over the mesh forwarder: serving a model bigger than any single node by splitting its layers across paired mesh peers.
agent/shell
Embedded coreutils fallback for the in-process shell.
 Embedded coreutils fallback for the in-process shell.
agent/sshclient
In-process SSH client over the cloudbox matrix tunnel.
 In-process SSH client over the cloudbox matrix tunnel.
agent/supervisor
Package supervisor is a minimal process supervisor: it keeps a fixed set of child Programs alive — start them, restart on exit with capped backoff, and gracefully stop them on shutdown.
 Package supervisor is a minimal process supervisor: it keeps a fixed set of child Programs alive — start them, restart on exit with capped backoff, and gracefully stop them on shutdown.
agent/sysinfo
Package sysinfo collects host capability information the outpost reports to cloudbox via the /apps poll loop.
 Package sysinfo collects host capability information the outpost reports to cloudbox via the /apps poll loop.
agent/sysload
Package sysload is the outpost's considerate system-load profiler.
 Package sysload is the outpost's considerate system-load profiler.
agent/upgrade
Package upgrade carries the self-upgrade machinery shared by the CLI (`outpost upgrade`, `outpost rollback`) and the cloudbox-pushed daemon route (POST /admin/upgrade).
 Package upgrade carries the self-upgrade machinery shared by the CLI (`outpost upgrade`, `outpost rollback`) and the cloudbox-pushed daemon route (POST /admin/upgrade).
agent/userkube
Package userkube owns the workflow for materializing a kubectl- ready kubeconfig from cloudbox onto this host's disk.
 Package userkube owns the workflow for materializing a kubectl- ready kubeconfig from cloudbox onto this host's disk.
agent/vknode
Package vknode is the per-outpost half of the cloudbox cluster: it joins a cloud-side Kubernetes API server as a virtual node and runs scheduled Pods as podman containers on the host.
 Package vknode is the per-outpost half of the cloudbox cluster: it joins a cloud-side Kubernetes API server as a virtual node and runs scheduled Pods as podman containers on the host.
agent/warm
Package warm implements the outpost's adaptive, considerate, always-on warm-serving plane.
 Package warm implements the outpost's adaptive, considerate, always-on warm-serving plane.
agent/ycode
Package ycode discovers and lifecycle-manages a `ycode serve` process running side-by-side with outpost on the same OS user account.
 Package ycode discovers and lifecycle-manages a `ycode serve` process running side-by-side with outpost on the same OS user account.
jitter
Package jitter provides randomized timing for retry/backoff loops so a fleet of hosts that fail or restart together does not retry in lockstep — a synchronized "thundering herd" that can overwhelm the shared cloudbox hub.
 Package jitter provides randomized timing for retry/backoff loops so a fleet of hosts that fail or restart together does not retry in lockstep — a synchronized "thundering herd" that can overwhelm the shared cloudbox hub.
scheduler
Package scheduler is a thin wrapper around robfig/cron/v3 that adds a JSONL ledger so each fired job leaves a durable record alongside the upgrade ledger (internal/agent/upgrade/ledger.go is its sibling shape — same Append+Tail pattern, different vocabulary).
 Package scheduler is a thin wrapper around robfig/cron/v3 that adds a JSONL ledger so each fired job leaves a durable record alongside the upgrade ledger (internal/agent/upgrade/ledger.go is its sibling shape — same Append+Tail pattern, different vocabulary).
telemetry
Package telemetry bootstraps the OTEL SDK for outpost and exposes the small set of helpers wire callers need (gin tracing middleware, reverse-proxy traceparent preservation, slog ↔ OTEL log bridge).
 Package telemetry bootstraps the OTEL SDK for outpost and exposes the small set of helpers wire callers need (gin tracing middleware, reverse-proxy traceparent preservation, slog ↔ OTEL log bridge).
util

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.