README
¶
outpost
The home-host agent for ai.dhnt.io.
One outpost binary runs on each machine you want to surface through the
portal. It registers with the portal using a one-time code, dials back
over a secure tunnel, and serves the local apps (HTTP, shell, desktop,
clipboard) so that authenticated portal users can reach them through
https://ai.dhnt.io/h/<host>/app/<name>/.
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
From source — if you have Go 1.25+ (note: go install …@latest does
not work here — 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.git && cd outpost
./scripts/build.sh # macOS / Linux → ./bin/outpost
git clone https://github.com/qiangli/outpost.git; cd outpost
powershell -ExecutionPolicy Bypass -File .\scripts\build.ps1 # Windows → .\bin\outpost.exe
Already have any outpost release installed? outpost build rebuilds
from GitHub source in one command — no system git needed. See
docs/building.md (or outpost docs building) for
all build paths, tag/commit pinning, and cross-compilation.
See outpost docs install (or docs/install.md) for the full guide: environment overrides (INSTALL_DIR, OUTPOST_VERSION, NO_SERVICE), Linux PAM auth via CGO_ENABLED=1, Windows Defender notes, and uninstall steps.
Pair with the portal
-
Sign in at https://ai.dhnt.io/admin/, open Hosts, click Generate invite code.
-
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 and
saves it to the default user-config path. The portal tells the agent
which transport to use; outpost start then dials in and starts the
local HTTP server.
By default ycode at http://127.0.0.1:8765 is registered as an app;
declare more with:
MATRIX_APPS="ycode=http://127.0.0.1:8765,jupyter=http://127.0.0.1:8888" \
outpost start
What outpost serves
/app/<name>/*— reverse-proxies any HTTP app you declare inMATRIX_APPS./shell— admin-tier PTY-wrapped shell (WebSocket)./desktop— admin-tier VNC relay (WebSocket)./clipboard— clipboard bridge./auth— credential check against the host OS by default, or against a custom--auth-urlendpoint for app-level user lists.
All of these are reached only through the portal — outpost binds its
HTTP server to loopback (127.0.0.1:<random>).
Build from source
outpost is fully open source under the MIT license. You don't have to trust the binaries we publish — clone the repo, read every line of code that talks to the portal, build your own binary, and pair that with ai.dhnt.io. Nothing is hidden, nothing phones home behind your back.
git clone https://github.com/qiangli/outpost
cd outpost
./scripts/build.sh # → ./bin/outpost
./bin/outpost register --server https://ai.dhnt.io --code <code> --name <host>
./bin/outpost start
Requires Go 1.25+. ./scripts/build.sh (and its Windows twin
.\scripts\build.ps1) first materializes the ../sh sibling the
go.mod replace directive needs, then runs go build ./cmd/outpost
with the version + commit baked into the binary so outpost version
reports a build you can trace back to a git SHA. Already have outpost
installed? outpost build does the whole flow — clone from GitHub,
sibling bootstrap, build — without system git, make, bash, or
coreutils; only the Go toolchain. Pin a version with
outpost build --ref v0.3.0 (tag) or --ref <sha> (any commit), then
swap it in with outpost upgrade --local <built>. The full guide is
docs/building.md (outpost docs building); see
docs/install.md for the CGO-enabled recipe needed
for Linux PAM auth (CGO_ENABLED=1 + libpam-dev) and Windows
Defender notes.
Forking, modifying, contributing — outpost has no proprietary
hooks. The wire protocol with cloudbox is documented inline in
internal/agent/portal/ (the exchange.go
round-trip is the only handshake), and every config key is in
docs/settings.md. A modified outpost that obeys
the same protocol will pair with the public portal the same way an
official binary does. PRs welcome.
Release notes: https://github.com/qiangli/outpost/releases.
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/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/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/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/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/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/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/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/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/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/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/vkpodman
Package vkpodman 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 vkpodman 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/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. |
|
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). |