Guide

Piomio on a server

A server stays on, so your agents keep working while your computer sleeps. One command installs Piomio there, and you sign in to your own Claude Code, Codex or Kimi Code on it.

You need Linux with systemd on x64 or arm64 (Ubuntu, Debian, Fedora and the like) and SSH access as root. On Alpine and other musl systems, use Docker.

The hub on the server

  1. 1

    Install

    Connect to the server over SSH as root and run the installer. It creates the user piomio without sudo, installs the libraries the agents’ browser needs and starts Piomio as that user’s service. At the end it prints the setup code, the line that opens the chat on your computer, and the brains it found. Running it again updates Piomio.

    curl -fsSL https://piomio.io/install.sh | sh
  2. 2

    Sign in to a brain

    Agents think with the CLI that the user piomio is signed in to, on your own plan. Sign in yourself, as that user. Codex, for example:

    sudo -iu piomio
curl -fsSL https://chatgpt.com/codex/install.sh | sh
codex login --device-auth

    Claude Code: curl -fsSL https://claude.ai/install.sh | bash, then claude. Kimi Code: curl -fsSL https://code.kimi.com/kimi-code/install.sh | bash, then kimi and /login. Piomio finds the sign-in within a minute, no restart needed. You can also skip this step and press Sign in in the chat later: it installs a missing CLI first.

  3. 3

    Open the chat

    The chat listens only on the server itself. On your computer, run the line the installer printed and keep it running:

    ssh -N -L 8080:localhost:8080 -L 8081:localhost:8081 root@<server-ip>

    Then open http://localhost:8080, enter the setup code and choose a password. The assistant takes you through the rest in the chat. Lost the code? sudo -iu piomio cat ~/.local/share/piomio/setup-code.

  4. 4

    Reach it from anywhere

    Say “turn on access from anywhere” in the chat and sign in to Tailscale with a free account. The hub gets a permanent link like https://piomio.<your-tailnet>.ts.net: any browser, the phone app and your other computers reach it there, with no tunnel and no open ports.

  5. 5

    Update with a button

    When a release is out, the server’s row in Machines shows Update, and the assistant offers it in the chat. Piomio checks the release’s signature, keeps a copy of the database and is back in about a minute. If the new version doesn’t start, it goes back to the previous one by itself.

Commands, after sudo -iu piomio

piomio version
the installed version
piomio backup
a copy of the database, the vault, agents and plugins in ~/.local/share/piomio/backups
piomio reset-password <…>
a new password for the chat
piomio devices pair
a QR code for the phone app, right in the terminal
systemctl --user restart piomio
a restart, for example after a change in ~/.config/piomio/env
journalctl --user -u piomio -f
the log
piomio uninstall
removes the app and the service; the data stays in ~/.local/share/piomio

A computer of your hub

  1. 1

    Let the server reach your hub

    A hub on a Mac or PC at home opens only there until you turn on access from anywhere: say “turn on access from anywhere” in its chat. If you skip this, the assistant offers it when you ask to connect a computer.

  2. 2

    Get an invite

    Say “connect a computer” in the chat and press the button on the card. You get a one-time link that works for an hour, like https://piomio.<your-tailnet>.ts.net/join/AB12CD34. Open it: under Server without a screen the page shows the next command with your link already in it.

  3. 3

    Run it on the server as root

    It creates the user piomio, puts Node.js and the hub’s piomio-node in its home and keeps them connected as a service. PIOMIO_NAME is what the computer is called in Machines; without it, the server’s host name.

    curl -fsSL https://piomio.io/install.sh | PIOMIO_NAME=vps sh -s -- https://piomio.<your-tailnet>.ts.net/join/<code>
  4. 4

    Sign in to a brain

    The same way as for a hub: sudo -iu piomio, then sign in to Codex, Claude Code or Kimi Code. They become the brains codex@vps, claude-code@vps and kimi@vps, and the hub sees a sign-in within a minute.

  5. 5

    Decide what agents may do there

    The server decides that, in ~/.piomio-node/policy.json: by default agents work only in ~/piomio-workspace, and running commands is off. A change takes effect by itself. Newer versions of piomio-node come from the hub: its row in Machines shows Update when it’s behind.

Commands, after sudo -iu piomio

piomio-node status
whether it’s paired, its policy, its CLIs and whether the hub answers
journalctl --user -u piomio-node -f
the log
piomio-node uninstall
removes the service; the key and the policy stay. Remove the computer in Machines too

Why not just the server’s IP address?

Piomio opens the chat only on 127.0.0.1, on purpose:

  • The chat (port 8080) speaks plain HTTP. Over the internet your password and session would travel unencrypted, and bots find an open port within minutes.
  • Passkeys work only over HTTPS or on localhost, so http://<ip>:8080 can’t use them.
  • Port 8081 is the security console: rules, the vault, the audit. It should never face the internet.

The safe ways in are the SSH tunnel, access from anywhere, or your own domain with HTTPS in front. The phones’ port 8082 is HTTPS with the hub’s own certificate, which the app pins from the QR code, so that one is fine to open: ufw allow 8082/tcp.

If you still want the bare address, with plain HTTP and no passkeys, put this in ~/.config/piomio/env:

PIOMIO_HOST=0.0.0.0
PIOMIO_PUBLIC_URL=http://<server-ip>:8080

Then, as root, ufw allow 8080/tcp (and only 8080: the console now listens on every address too, so 8081 stays closed), and as piomio, systemctl --user restart piomio. Without PIOMIO_PUBLIC_URL the hub refuses every address but localhost.

If something goes wrong

The installer can’t reach the hub

The invite link has to open from the server: try curl -I <link> there. A hub at home needs access from anywhere turned on. Each link works once and for an hour, so ask for a new one.

A brain is signed in, but Piomio doesn’t see it

It has to be signed in as the user Piomio runs as, piomio, not as root. Check with sudo -iu piomio, then codex login status or claude auth status.

systemctl --user can’t connect to the bus

Open the user’s shell with sudo -iu piomio: the installer set it up so that systemctl --user and journalctl --user work there.

The chat doesn’t open on localhost:8080

The ssh -L line has to keep running while you use the chat. On the server, sudo -iu piomio, then systemctl --user status piomio and journalctl --user -u piomio -n 50 show whether Piomio runs and what stops it.

In Docker

The image runs brains and plugins as separate users with their own folders and can block their network at the kernel: the strongest isolation. On a server with Docker and Git:

git clone https://github.com/legostin/piomio.git && cd piomio
docker compose up -d
docker compose logs piomio | grep -A1 "Piomio:"

Compose pulls the ready image ghcr.io/legostin/piomio, and the last line prints the setup code. The chat opens the same way, through the ssh -L line above. Settings go in .env next to docker-compose.yml (.env.example lists each one). To update: git pull && docker compose pull && docker compose up -d.