⁠linuxserver/pelorus⁠

⁠This readme has been truncated from the full version found HERE⁠

Pelorus⁠ is an AI navigator for Selkies-powered Linux desktops. Pelorus runs a FastAPI server that gives an LLM agent (Ollama, OpenAI-compatible, or Gemini) control over mouse, keyboard, screenshot, and window management via the Pixelflux computer-use backend⁠, a Linux accessibility tree (AT-SPI), and optional KWin D-Bus integration.

⁠Application Setup

https://github.com/user-attachments/assets/226bf96f-a6d6-46c2-95f4-677334dddd03⁠

⁠Split Plane View

Pelorus ships with a split plane landing page served over HTTPS on port 3001. The left pane loads the raw Pelorus chat UI and the right pane loads your Selkies desktop session in an iframe. Both are also available directly via their subfolders:

• Pelorus UI - https://yourhost:3001/pelorus/
• Selkies Session - https://yourhost:3001/selkies/

HTTP on port 3000 serves only the Selkies desktop session (no Pelorus UI).

⁠LLM Provider

By default the agent is configured to use opencode big-pickle for demo purposes. Users are encouraged to link up their own paid providers or a locally hosted endpoint.

If you would like to support opencode, you can sign up for opencode Go⁠.

⁠Provider Environment Variables

Set these to setup a provider on first boot:

⁠Example API Call

Use -k with curl to skip certificate verification (the container uses a self-signed cert by default):

curl -k -s https://localhost:3001/pelorus/api/run \
  -H 'Content-Type: application/json' \
  -d '{"prompt":"open kate please","response_format":"minimal","stream":true}'

⁠Usage

docker run -d \
  --name=pelorus \
  -e PUID=1000 \
  -e PGID=1000 \
  -e TZ=Etc/UTC \
  -p 3001:3001 \
  -v /path/to/pelorus/config:/config \
  --shm-size="1gb" \
  --restart unless-stopped \
  lscr.io/linuxserver/pelorus:latest