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. Put the hub behind your domain — either with Synsema directly:

synsema serve ~/lampson/hub.syn --port 443 --domain lampson.example.com --tls-auto you@example.com

or behind the reverse proxy you already run. Set LAMPSON_PUBLIC_URL=https://lampson.example.com so approval links carry the right address. See Scheduled tasks for approving from your phone.

The web API answers only loopback clients; through your proxy, protect it the way you protect anything else on that host (basic auth, an identity-aware proxy, a VPN). The one-time approval links are the one path meant to be public — the token is the authorization and it dies with the deadline.

Requirements§

• Linux: the synsema binary needs glibc ≥ 2.39 (Ubuntu 24.04+, Debian 13+, Fedora 40+).
• Windows: PowerShell (built-in is fine) and Git for Windows (its bash runs the commands).
• macOS: nothing extra.