Backend

Pipe v0.50.5

The agent backend. It runs on the server (Docker, natively with systemd or in Kubernetes – deploy.md) and exposes a local Unix socket and TCP port 127.0.0.1:7379 for clients.

Requirements#

• Linux, Python 3.11+
• docker mode: Docker 24+ with Compose v2 (the installer adds them from the distribution's repository)
• native mode: systemd; kubernetes mode: a cluster with PVC

Modules#

Configuration#

Set up the LLM provider#

From the repository root run the wizard (it creates backend/.env from .env.example by itself):

python3 -m backend.configure

The wizard:

1. shows the list of providers and asks for the API key (with a link to where to get it),
2. fetches the current list of models straight from the provider's API, so new models show up right away without updating Pipe,
3. checks live whether the chosen model supports tool calling (without it the agent can't run any command),
4. writes backend/.env (creating it from .env.example if it doesn't exist; permissions 600).

The wizard uses only Python's standard library, so there is nothing to install.

Useful modes:

python3 -m backend.configure --check      # test the current configuration (model list + tool calling)
python3 -m backend.configure --models     # current models of the current provider
python3 -m backend.configure --providers  # all available providers

Built-in providers#

All through an API compatible with OpenAI Chat Completions. Addresses verified in September 2026.

The default model is only a starting point. At startup the backend checks whether the configured model is still on the provider's list and prints a warning with suggestions if it was retired.

Privacy: Pipe sends the provider logs, configs and command output from the server (secrets are redacted). On the free tier of the Gemini API Google may use prompt content to improve its services and humans may read it. The wizard, pipe web and the CLI warn about this when you pick Gemini. On a production server enable billing in Google AI Studio or choose another provider, for example a local Ollama.

No model (LLM_PROVIDER=none)#

Pipe can run without any model. Nothing leaves the server and nothing costs money, and these keep working: watching and alerts, snapshots and "what changed", the morning digest, certificate and site checks, the security audit, the journal and /undo, diagrams, webhooks (the alert arrives, nobody investigates it) and the MCP gateway for other agents (without ask_pipe). Chat, routines and alert investigations answer that there is no model. When you add a provider later in pipe web or /providers, chat turns on without a restart.

In the wizard it is the last item on the list; without questions: LLM_PROVIDER=none bash scripts/install-server.sh -y.

Configuring .env by hand#

Instead of the wizard you can edit backend/.env by hand:

LLM_PROVIDER=openai
LLM_API_KEY=sk-...
LLM_MODEL=            # empty = the provider's default model

Instead of LLM_API_KEY you can set a provider-specific variable, for example OPENAI_API_KEY, GEMINI_API_KEY, ANTHROPIC_API_KEY; LLM_API_KEY takes precedence.

The provider from .env is the base provider, the one the backend starts with. More can be added without a restart in pipe web (the provider screen, /provider): the key goes to DATA_DIR/llm_keys.json (0600), and the switcher in the conversation changes the provider of the whole agent. Preset variables set next to LLM_API_KEY (for example OPENAI_API_KEY, GROQ_API_KEY) also count as ready providers in the switcher. WORKER_MODEL, LLM_REASONING_EFFORT and the LLM_PRICE_* prices apply only to the base provider.

Optionally:

LLM_BASE_URL=https://proxy.example.com/v1   # overrides the preset's address (e.g. a company proxy)
LLM_REASONING_EFFORT=low                     # for models that support this parameter
LLM_TIMEOUT=120                              # LLM response timeout in seconds

Old .env files (only LLM_BASE_URL + LLM_API_KEY + LLM_MODEL, without LLM_PROVIDER) keep working; the provider is recognised by its address.

Your own provider#

You add any OpenAI-compatible endpoint (vLLM, LM Studio, LiteLLM, a company proxy...) with the wizard: pick Other and give the address. The provider is saved in backend/data/providers.json and from then on it is available like a built-in one (LLM_PROVIDER=<id>).

You can also edit this file by hand:

{
  "providers": [
    {
      "id": "my-vllm",
      "name": "My vLLM",
      "base_url": "http://192.168.1.10:8000/v1",
      "default_model": "qwen3",
      "requires_key": false
    }
  ]
}

An entry with the id of a built-in provider overrides it, which is how you fix an outdated address without waiting for a new Pipe version. The backend/data/ directory is mounted in the container, so changes don't need an image rebuild; docker-compose restart vps-agent is enough.

Ollama (local models)#

The container sees the host at host.docker.internal (set in docker-compose.yml). Ollama listens only on 127.0.0.1 by default, so you have to start it with OLLAMA_HOST=0.0.0.0 for the container to see it. The model must support tool calling; the wizard checks that.

Protecting with a token#

# Protection (optional, but strongly recommended)
# When set, every request, including confirming an operation, must contain
# this token. It protects the socket and the TCP interface from other processes on the server.
# Give the same token to the clients: to the CLI with --token (or the AGENT_TOKEN variable),
# to the Telegram bot with AGENT_TOKEN in clients/telegram/.env.
# Empty = no token required.
AGENT_TOKEN=your-secret-token

Agent memory: SERVER.md and skills#

The agent has several kinds of persistent memory: SERVER.md, skills (below), and also DIRECTORY (a map of repositories and directories) and VIBE (conversation style), described in features.md. Everything lives on the host in backend/data/ (in the container /app/data, the DATA_DIR variable), survives a restart and an image rebuild, and doesn't go into git. targets.json, routines.json, reminders.json, watch_state.json and the audit log are there too.

SERVER.md#

The agent's notes about the server, like AGENTS.md but for a server. The agent updates them by itself (the server_md tool) when it learns a lasting fact: services, containers, domains, ports, important paths, your decisions. The whole file is added to the system prompt of every conversation (up to 12,000 characters; the file itself can have up to 20,000).

To start you can ask: "explore the server and create SERVER.md". You can also edit the file by hand: backend/data/SERVER.md.

Skills#

Saved reusable procedures, in the Agent Skills format:

backend/data/skills/<name>/SKILL.md

---
name: renew-certificate
description: Renewing the TLS certificate for nginx
---

1. `certbot renew`
2. `nginx -t && systemctl reload nginx`
3. Check the certificate's expiry date.

The system prompt has only the list of skills (name and description). The agent loads the full content with the skill_manage tool when a task matches the description, so many skills don't clog the context. The agent creates a skill after carrying out a multi-step procedure that will come up again, or when you ask.

Every skill also gets its own command on Telegram and in the CLI: dashes turn into _, and the name is shortened to 32 characters (Telegram's limit), for example renew-certificate → /renew_certificate. A skill whose name is taken by a built-in command (status, server, skills, ...) gets no command; run it through /skills or with plain text.

Memory security#

• Writing to memory doesn't require confirmation, because it doesn't change the server, only the agent's notes. Every write goes into the audit log (only the path, without content). The exceptions (saving a skill, overwriting the whole SERVER.md) are described in Security.
• Skills and SERVER.md don't bypass the security rules: every command from them still goes through classification and the confirmation requirement.
• SERVER.md is sent to the LLM provider with every request, so writing obvious secrets (private keys, API keys, tokens, password=...) is refused. The agent writes down where a secret is stored, not the secret itself.

Running#

docker-compose up -d

Checking#

docker logs vps-agent --tail 20

You should see:

[VPS Agent] Unix socket : /tmp/vps-agent.sock
[VPS Agent] TCP         : 0.0.0.0:7379 (localhost only — use an SSH tunnel)
[VPS Agent] Provider    : Google Gemini (https://generativelanguage.googleapis.com/v1beta/openai/)
[VPS Agent] Model       : gemini-3.8-flash
[VPS Agent] Runtime     : docker (host: /hostfs, proc: /hostproc)
[VPS Agent] Diagrams    : mermaidx
[VPS Agent] Watcher     : every 120 s
[VPS Agent] Server ready. Ctrl+C to stop.

Agent tools#

With TOOLS_MODE=lazy (default) the model starts with the basic tools only (commands, files, git, system state, Docker, network, server history, project, load_tools). The memory, security, schedule, fleet, web, diagram and update groups turn on by themselves when a message needs them, or through load_tools.

More .env settings#

Stopping#

docker-compose down          # docker mode
systemctl stop pipe          # native mode

Edit this page on GitHub