Overview

potaru is a self-hosted remote-shell / remote-admin tool. A public server lets an authenticated operator open an interactive reverse shell, from the browser, to any machine running the agent (the potaru-client binary).

Two binaries, one module (okonomi.cloud/potaru):

potaru-server — runs on a public host. Terminates the agent tunnel (TLS, agents dial in) and the admin web UI/API (browsers connect in). It never dials out.
potaru (the agent, built from cmd/client) — runs on any machine you want reverse-shell access to. Dials out to the server over a long-lived TLS connection — no inbound ports needed on the target, works behind NAT/firewalls — and spawns a PTY-backed shell on request.

How it works

An admin creates an enrollment token in the web UI (or via potaru-server create-enrollment-token).
The agent enrolls once with that token — the server mints a permanent, per-agent secret on first connect, which the agent persists and uses for every reconnect after that. The enrollment token itself is never reused.
An operator logs into the admin web UI, sees which agents are online, and clicks "open shell" on one.
The server opens a new multiplexed stream (yamux over the one TLS connection) to that agent's live session and asks it to spawn a shell; the agent pipes a PTY's I/O over the stream.
The browser bridges a WebSocket to that stream via a real terminal emulator (xterm.js) — nothing installed on the operator's machine beyond a browser.

Every shell session (open and close) and every mutating admin action (enrolling/revoking tokens, deleting agents) is recorded in an audit log.

Scope

The agent targets Linux, macOS, and Windows (windows/amd64). Windows uses a real ConPTY-backed shell, same as Linux/macOS use a real PTY — see Agent reference.

State

State (sqlite database) lives under the server's state directory — no external database, no other services required. TLS is currently self-signed only (--self-signed on the server, --insecure on the agent); real ACME-issued certificates are a planned addition.