Agent reference

The agent binary is built from cmd/client and installs as potaru.

Commands

potaru init [flags]        enroll this machine with a potaru-server
potaru run [flags]         run the dial/reconnect loop (foreground)
potaru install / exec-install [--bin DIR]   place this binary on PATH
potaru uninstall / exec-uninstall [--yes]   remove it
potaru version             print version and exit

`init` flags

Flag	Description
`--server`	potaru-server tunnel address (`host:port`, required)
`--token`	enrollment token from `potaru-server create-enrollment-token` (required)
`--insecure`	skip TLS verification — needed while the server runs `--self-signed`

init only writes local config (~/.config/potaru/config.json, override with POTARU_CONFIG) — no network call happens until run. Enrollment itself happens transparently on run's first successful connect: the server recognizes the enrollment token being redeemed for the first time and mints this agent's own permanent secret, which run persists in place of the enrollment token.

`run` flags / env vars

Flag	Env var	Description
(none)	`POTARU_SERVER`	overrides the saved config's server address
(none)	`POTARU_TOKEN`	overrides the saved config's token
(none)	`POTARU_INSECURE`	overrides the saved config's insecure flag
`--verbose`	`POTARU_VERBOSE`	debug-level logging

The env vars exist so run works without an init step at all — the path Docker/container deployments use (see Install → Docker). Either a saved config (init) or both POTARU_SERVER/POTARU_TOKEN set is required.

What actually runs when a shell is opened

The agent spawns a real shell process as whatever OS user (or container user) the agent process itself runs as. On Linux/macOS: $SHELL, falling back to /bin/bash, then /bin/sh. On Windows: powershell.exe if present, else cmd.exe. It never elevates privileges. If you want root/ admin access, that's an explicit choice you make by running the agent with that privilege yourself — the product never defaults to it.

Platform support

Linux and macOS (via creack/pty, a real PTY). Windows (via a real ConPTY, github.com/UserExistsError/conpty) ships as windows/amd64 only for now — see Install for the PowerShell installer.