outpost

Overview ¶

`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. POSTs to cloudbox's /h/:host/elevate endpoint, captures the returned matrix_elev cookie, and caches it on disk so later `outpost ssh-proxy` invocations (both human and agentic) can ride on it until idle / absolute expiry.

`outpost jobs / fg / bg / kill` are the external job-control commands the matrix shell points users at when they try to run `fg`/`bg`/`jobs` in-shell — those builtins can't work because subshells in the qiangli/sh interpreter are goroutines, not real OS processes. Outpost records each detached PID via the WithBgPidCallback hook on the shell runner; these commands read that persistent registry.

Windows: see jobs_windows.go — the signal-based job-control model is Unix-specific (no SIGSTOP/SIGCONT/SIGUSR1/SIGUSR2 equivalents on Windows), so the verbs stub out to "not supported."

Command outpost runs on a home host: it pairs with the portal and surfaces local apps (web, shell, desktop, clipboard) through a tunnel.

MCP client glue for the `outpost apps|builtins|status|unpair` family of subcommands. Each subcommand is a thin wrapper that connects to the running daemon's /mcp/ endpoint with a bearer token, calls one tool / reads one resource, and pretty-prints the result.

Three ways to address the daemon (precedence high → low):

1. `--host`/`--token` persistent flags on the root command.
2. `--remote <name>` persistent flag, pointing at a cached entry in ~/.config/outpost/remotes/<name>.json (written by `outpost remote login <name>`).
3. $OUTPOST_HOST / $OUTPOST_ADMIN_ADDR + $OUTPOST_MCP_TOKEN env variables.
4. Implicit local: 127.0.0.1:17777 + bearer from the local FileConfig (mode 0600, same OS user). Only this last path requires that the daemon is on the same host as the CLI.

Daemon-not-running: the HTTP dial fails with a friendly error. The dedicated `--offline` flag (on a few mutate subcommands) bypasses MCP entirely and writes the FileConfig directly via admincore — useful for installer scripts.

`outpost outbound …` is the CLI mirror of the admin UI's Outbound section. It drives the running local outpost's admin-UI HTTP API on 127.0.0.1:17777 — it does NOT reimplement the elevate/pinger logic. All commands assume the local outpost is already running (`outpost start`) and paired; the binary will print a friendly hint if the admin UI is unreachable.

Auth model: each invocation reads ~/.cache/outpost/admin.cookie. If missing or expired (1h TTL, wiped on outpost restart), commands print "run `outpost outbound login` first" and exit non-zero. Login itself prompts for the LOCAL OS password (same gate as the admin UI's login page); `connect` prompts for the REMOTE host's OS password (the one cloudbox's elevate endpoint will verify).

`outpost pool status` is the operator's read-only view of this outpost's LLM-pool participation. Inspects the persisted FileConfig + probes the locally-configured Ollama daemon directly — does not talk to the running outpost process (no admin-UI login dance, no session cookie). For live watcher state (last push time, in-flight counter), open the admin UI; this CLI is for "is the pool wired correctly?" sanity checks and scripting.

`outpost remote {login,logout,list}` caches the bearer token + admin endpoint for outposts on other machines so the CLI can target them with `outpost --remote <name> apps stop foo` instead of piping $OUTPOST_HOST / $OUTPOST_MCP_TOKEN on every invocation.

Cache layout (mode 0600, same OS user only):

~/.config/outpost/remotes/<name>.json
  { "addr": "host.local:17777", "token": "<bearer>" }

Names are arbitrary aliases — typically the LAN hostname, but nothing here interprets them. Token is the value of the remote outpost's FileConfig.MCPBearerToken (printed by `outpost mcp endpoint` on that machine).

`outpost run --label X -- <cmd>` is the supported alternative to `launchctl submit`, which silently no-ops inside the matrix-shell because the SSH session inherits a launchd system-domain context that doesn't have `submit` capability (see docs/matrix-shell-deferred-bugs.md #8).

What this verb does: generate a LaunchAgent plist for the operator's command, bootstrap it into the per-user `gui/<uid>` domain via `launchctl bootstrap`, and persist the plist under ~/Library/LaunchAgents so it auto-loads at next login too. Pair with `outpost run --list` (show outpost-managed jobs) and `outpost run --remove <label>` (bootout + delete plist).

macOS only — `launchctl bootstrap` doesn't exist on Linux/Windows. The verb is registered regardless so the help text shows the recipe on every platform, but RunE errors out early on non-darwin so operator scripts get a clear message instead of a cryptic exec failure.

SSH client-side helpers: `outpost ssh-proxy` (used as an SSH ProxyCommand to bridge a local `ssh` invocation to the remote outpost over the matrix tunnel) and `outpost ssh-config` (prints ~/.ssh/config stanzas for hosts visible to this account).