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+:
go install github.com/qiangli/outpost/cmd/outpost@latest
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
go build ./cmd/outpost
Requires Go 1.25+. See docs/install.md for the CGO-enabled recipe needed for Linux PAM auth.
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/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/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/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
Package shell is the in-process bash interpreter (qiangli/sh / mvdan.cc/sh) wrapped in a PTY so xterm.js sees a real TTY: line discipline, echo, backspace, resize, and Ctrl-C all flow through the kernel TTY layer just as they would for a child `bash` process — except there is no child process.
|
Package shell is the in-process bash interpreter (qiangli/sh / mvdan.cc/sh) wrapped in a PTY so xterm.js sees a real TTY: line discipline, echo, backspace, resize, and Ctrl-C all flow through the kernel TTY layer just as they would for a child `bash` process — except there is no child process. |
|
agent/sshclient
In-process SSH client over the cloudbox matrix tunnel.
|
In-process SSH client over the cloudbox matrix tunnel. |
|
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. |
Click to show internal directories.
Click to hide internal directories.