Reference

Docker and servers

Docker§

The whole agent — including the commands it runs — stays inside the container. Mount your project as the workspace:

docker run --rm -p 8080:8080 -v "$PWD:/lampson/workspace" \
  -e LAMPSON_PROVIDER=deepseek -e LAMPSON_API_KEY=sk-... ghcr.io/kitecosmic/lampson

Then open http://127.0.0.1:8080. From a clone, docker build -t lampson .; docker-compose.yml does the same with persistent sessions and memory.

On a VPS§

Install as on any Linux box (the one-liner or npm i -g lampson), then keep the hub alive:

lampson --install        # systemd --user unit, Restart=always
lampson --hub status

Workspace processes never leave loopback. To reach it from outside with your own domain and HTTPS (optional):

lampson --domain lampson.example.com --email you@example.com

Lampson gets a free Let's Encrypt certificate, renews it on its own and serves the hub at https://lampson.example.com; the hub stops listening on the network. You need a DNS A/AAAA record pointing to the server, ports 80 and 443 open and, on Linux without root, sudo setcap cap_net_bind_service=+ep $(command -v synsema). lampson --domain shows the status and lampson --domain off puts everything back. Without --domain nothing changes. To pair your phone from the server: lampson --pair over SSH prints the QR in the terminal (On your phone).

From your phone§

Pairing the phone with a passkey, installing the app and reaching your home PC through a tunnel: On your phone.

One-time approval links stay public on purpose — the token is the authorization and it dies with the deadline. LAMPSON_WEB_TOKEN (Bearer) still works for scripts. See Scheduled tasks to approve from your phone.

Requirements§

• Linux: the synsema binary needs glibc ≥ 2.17 (any distribution since 2014: Ubuntu 20.04+, Debian 11+, RHEL 7+).
• Windows: PowerShell (built-in is fine) and Git for Windows (its bash runs the commands).
• macOS: nothing extra.