outpost

module

v0.0.1 Latest Latest Go to latest Published: May 27, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/qiangli/outpost

Links

Open Source Insights

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

go install github.com/qiangli/outpost/cmd/outpost@latest

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 in MATRIX_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-url endpoint 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

go build ./cmd/outpost

Requires Go 1.25+.

release notes — see github.com/qiangli/outpost/releases

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

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/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/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/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/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/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.
util