Quick start – step by step

Pipe v0.50.5

Try it without a server#

No spare server, or you want to see how Pipe works first? On your own computer with Docker:

git clone https://github.com/Kvmyk/pipe && cd pipe
LLM_PROVIDER=gemini LLM_API_KEY=... python3 sandbox/run.py try --scenario nginx-502
pipe --no-tunnel --local-port 7390        # or: pipe web --no-tunnel --local-port 7390

This starts a container that pretends to be a small server with a shop (nginx and an app), with Pipe inside. With --scenario the server starts broken: nginx-502 (wrong port in nginx), app-down (the app won't start), static-403 (wrong permissions), disk-hog (a forgotten big log). Ask Pipe for help and watch it look for the cause, ask for approval and take backups. Without a key the sandbox still starts, and Pipe then runs without a model. Stop it with docker rm -f pipe-sandbox.

The same scenarios are used to evaluate models: python3 sandbox/run.py eval runs each one, approves every proposed change and checks whether the server was really fixed (details: sandbox/README.md).

Prerequisites#

1. On the server – the agent backend running
2. On your laptop – Python 3.11+ and SSH access

A shorter way: install the client (step 2, you can skip the server address) and type pipe web. The page asks what you want to do and sets Pipe up itself on this computer (Docker) or on your server (address and an SSH password or key). Steps 1 and 3 then happen on their own.

Step 1: Start the backend on the server#

Log in to the server over SSH and run:

git clone https://github.com/Kvmyk/pipe
cd pipe
sudo bash scripts/install-server.sh  # or --mode native (without Docker), --lang pl for Polish

The wizard asks for the LLM provider and API key, fetches the current list of models, checks that the chosen model supports tool calling, and writes backend/.env. No key? Pick Google Gemini – you can create a free key at https://aistudio.google.com/apikey (on the free tier Google may learn from your prompts, so on production enable billing). You can also pick No model: Pipe watches the server and sends alerts and reports, and nothing leaves the server; you turn chat on later (backend.md).

The script installs Docker (if it is missing) and starts the backend. The same by hand: python3 -m backend.configure && cd backend && docker compose up -d --build.

Check that it works:

cd backend && docker compose logs vps-agent
# Should show: [VPS Agent] Server ready.

You can create a new cloud server with Pipe on it right away – cloud-init. Kubernetes: deploy/kubernetes.

Step 2: Install the CLI on your laptop#

git clone https://github.com/Kvmyk/pipe
cd pipe

Windows (PowerShell)#

.\install.ps1
# The script asks for the server address, e.g. root@server.example.com

Linux / macOS (bash/zsh)#

bash install.sh
# The script asks for the server address, e.g. root@server.example.com

The script:

• installs the Python dependencies (rich)
• adds a pipe function to your terminal profile
• from then on, typing pipe in any terminal is enough

Step 3: Connect to the agent#

pipe

The CLI automatically:

1. Sets up the SSH tunnel (asks for a password if needed)
2. Connects to the agent on the server
3. Waits for your requests

To begin: /map (a diagram of what runs on the server) and /server (the agent explores the server and writes down what it learned in SERVER.md and DIRECTORY).

Example session#

 pipe   Autonomous AI agent for managing a Linux server

 server    root@server.example.com
 commands  /status  /report  /changes  /map  /server  /skills  /help  /exit

Connected to the agent on root@server.example.com
──────────────────────────────────────────────────────────────────────

› how much free disk space do I have?

The disk is 79% full -- about 4.2 GB left.
The largest directories are /var/log (1.1 GB) and /home (2.3 GB).
Do you want to clean up the logs? (`journalctl --vacuum-time=7d`)

› show nginx errors from the last hour

› restart nginx

╭─  I need your approval  ─────────────────────────────────────────────╮
│                                                                      │
│    $ systemctl restart nginx                                         │
│                                                                      │
│  Safety fuse                                                         │
│   ✓  check before                   nginx -t                         │
│      (failure = I won't run it)                                      │
│   ✓  verify after                   nginx service active             │
│                                     sites that work now must         │
│                                     still work after the change      │
╰──────────────────────────────────────────────────────────────────────╯

Run it? [y/n] (n): y
✓ Approved — running...
nginx restarted, verification passed.

› exit
Goodbye!

The command in the panel is exactly what will run. Below it is the safety-fuse plan: what Pipe checks before and after the change (details: Changes with a safety fuse).

pipe shortcut options#

You can also pass extra options:

pipe --ssh-port 2222       # non-standard SSH port
pipe --key ~/.ssh/id_rsa   # a specific SSH key
pipe --session my-session  # keep the session history
pipe --lang pl             # Polish CLI messages

Problems#

Edit this page on GitHub