Set up Pengy
Pengy is the AI agent built into every edition. It can read files, run commands and search the web for you, each one only after you approve it. It ships without a model: before it can answer anything, you tell it where one is.
Where Pengy is
| Core | Server | Desktop | |
|---|---|---|---|
pengy-cli, in a terminal | ✓ | ✓ | ✓ |
pengy-web, in a browser | ✓ | ✓ | |
| Pengy, the app in the menu | ✓ |
All three share one set of settings and one chat history, per user. Set it up in one and the others are ready too.
Point it at a model
Pengy speaks the OpenAI-compatible API, which nearly every model server offers. It needs two
settings: the server's base URL and a model name (plus an
API key for a hosted service). In pengy-cli:
pengy-cli
/baseurl http://192.168.1.50:11434/v1 # where the model server is
/models # what it offers
/model qwen3:8b # pick one
In the app and the web UI it's the same three fields under ⚙ Settings, with a button that fetches the model list. The settings are saved, so this is a one-time job.
Which server?
| Where the model runs | Base URL |
|---|---|
| Ollama on another machine | http://that-machine:11434/v1
(Ollama must listen on the network: OLLAMA_HOST=0.0.0.0) |
| llama.cpp on this machine | http://127.0.0.1:8080/v1 |
| LM Studio | http://that-machine:1234/v1 |
| vLLM | http://that-machine:8000/v1 |
| OpenAI | https://api.openai.com/v1, with /apikey sk-… |
| OpenRouter | https://openrouter.ai/api/v1, with a key |
| Groq | https://api.groq.com/openai/v1, with a key |
Pengy's default URL is http://127.0.0.1:11434/v1, Ollama on the same machine.
PengyOS doesn't ship Ollama, so on a fresh install you'll always set the URL. To run a model on
the PengyOS machine itself, build llama.cpp in the dev box
(or run Ollama in a podman container).
Pengy works the machine through tool calls, so pick a model that handles tools well. Small models (a few billion parameters) answer questions fine but often fumble multi-step jobs.
A quick check that it's working, from any terminal:
pengy-cli --no-save "What edition of PengyOS is this?"
Approving what it does
Out of the box Pengy asks before every tool call: each command it wants to run, each file it wants to read or write. You can loosen that:
| Setting | Pengy asks before… |
|---|---|
none (the default) | every tool call |
safe | anything that changes something; reading files and searching run without asking |
all | nothing. Every call runs without asking |
/yolo safe # in pengy-cli; "Tool Confirmation" in Settings elsewhere
Pengy runs as you, with your permissions. With all, anything the model decides to
do happens, including sudo if you're an administrator and your password is cached.
Keep the default until you trust the model.
The web UI from another computer
pengy-web listens only on the machine itself (port 5000), so a headless Server's
Pengy is reached through SSH rather than opened to the network:
# on the server, as your user (or as a user service; see below)
pengy-web
# on your laptop
ssh -L 5000:127.0.0.1:5000 you@server
# then browse to http://localhost:5000
To keep it running without a login session, make it a user service on the server:
mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/pengy-web.service <<'EOF'
[Unit]
Description=Pengy web UI
[Service]
ExecStart=/usr/bin/pengy-web
Restart=on-failure
[Install]
WantedBy=default.target
EOF
systemctl --user enable --now pengy-web
sudo loginctl enable-linger "$USER" # keep user services running after you log out
Anyone who can reach the web UI can do what Pengy can do as you, so keep it on localhost behind
SSH. If you put it behind a reverse proxy anyway, pass the proxy's name with
pengy-web --trusted-host pengy.example.com and add authentication in the proxy.
Where its settings live
~/.config/pengy/settings.json: the URL, key, model, approval mode and the system message. All three versions read and write it./configinpengy-clishows it.~/.config/pengy/also holds your chats and saved tasks. It's in your home, on the data partition, so it survives updates and is in your backups.- The API key is stored there in plain text, readable only by you.