potaru

Install

Server (public host)

curl -fsSL https://potaru.okonomi.cloud/server/install.sh | sudo bash

This downloads the release binary (SHA-256 verified) and places it on your PATH via the binary's own exec-install. It does not set up a systemd service yet (that's a planned addition) — run it yourself:

sudo potaru-server run --self-signed --state-dir /var/lib/potaru \
  --tunnel-addr :7000 --https-addr :8443

Visit https://<your-host>:8443 (click through the self-signed cert warning) and create the admin account from the setup screen. Create an enrollment token from the dashboard, or headlessly:

potaru-server create-enrollment-token --label "my-laptop" --max-uses 1 --ttl 24h

Agent (any target machine)

Linux / macOS:

curl -fsSL https://potaru.okonomi.cloud/client/install.sh | bash

No root needed — this just places the binary on your PATH.

Windows (PowerShell):

irm https://potaru.okonomi.cloud/client/install.ps1 | iex

No admin rights needed — places potaru.exe in %LOCALAPPDATA%\potaru and adds it to your user PATH.

Then enroll and run (same on every platform):

potaru init --server <server-host>:7000 --token <the-enrollment-token>
potaru run

The agent shows up online in the dashboard within a few seconds. run needs to keep running in the foreground — wire it into your own service manager (systemd, launchd, a process supervisor) to keep it alive across reboots. A built-in service install (like the sibling products offer) is a planned addition.

Docker

See Run with Docker below — no install script needed, pull the images directly.

Run with Docker

services:
  server:
    image: okonomigmbh/potaru:latest
    restart: unless-stopped
    ports:
      - "8443:8443"
      - "7000:7000"
    environment:
      POTARU_SELF_SIGNED: "true"
    volumes:
      - potaru-state:/var/lib/potaru

  client:
    image: okonomigmbh/potaru-client:latest
    restart: unless-stopped
    environment:
      POTARU_SERVER: example.com:7000
      POTARU_TOKEN: pt_enroll_...   # enrollment token (first run only)
      POTARU_INSECURE: "true"       # dev only: server is using --self-signed
    volumes:
      - potaru-client-config:/home/potaru/.config/potaru

volumes:
  potaru-state:
  potaru-client-config:

<!-- SYNC: this block mirrors deploy/docker/compose.yaml in the potaru repo. If you change ports, env vars, or image tags there, update this too. -->

The agent's own permanent secret is minted on first connect and persisted to the mounted volume, so a container restart reconnects without needing the enrollment token again.

← Overview Quick start →