TL;DR: Running Pi in 5 Minutes

Pi is a minimal, MIT-licensed AI coding agent harness from Earendil that lives in your terminal. It ships with four tools — read, write, edit, bash — talks to 15+ model providers, stores every conversation as a branching session tree, and is extended through extensions, skills, prompt templates and packages instead of a bloated feature list. Running it on a cheap Netcup VPS turns it into an always-on agent you can SSH into from any machine.

Key points about Pi:

• Minimal core, maximum control — four built-in tools, everything else is opt-in
• 15+ providers, hundreds of models — Anthropic, OpenAI, Google, Azure, Bedrock, Mistral, Groq, plus local llama.cpp and Ollama endpoints
• Tree-structured sessions — branch, fork, clone, compact and export any conversation
• Headless modes — --print, --mode json and --mode rpc make Pi scriptable from cron and CI
• Open source — MIT licensed, installable via a one-line script, npm or Nix
• Runs great on a small VPS — the model does the heavy lifting remotely, so 4 vCores and 8 GB RAM are plenty

Install Pi on a fresh Netcup VPS in four commands:

ssh root@your-server-ip
curl -fsSL https://pi.dev/install.sh | sh
pi --version
pi

Then run /login inside the TUI, pick your provider, and start working.

Recommended server: Netcup VPS 1000 G12.5 — 4 vCore, 8 GB ECC RAM, 128 GB SSD, 2.5 Gbit/s with traffic flat rate, at EUR 12.18/month (excl. VAT).

Use one of these coupon codes for 1 month free:

6877nc17911959135
6877nc17911959133
6877nc17911959132

Introduction

Most AI coding agents arrive with a worldview already installed. They decide which tools exist, when to ask permission, how the terminal looks, and where your conversation history goes. That works until your workflow does not match the one the vendor imagined — and then you are fighting the tool instead of using it.

Pi takes the opposite position. Its tagline says it plainly: "There are many agent harnesses but this one is yours." Pi is a harness, not a product: a small, auditable core that handles the agent loop, model requests, tool execution and session storage, with every opinionated behaviour pushed out into extensions you choose to load.

That design makes Pi an unusually good fit for self-hosting on a VPS. The agent itself is lightweight — the expensive inference happens on your model provider's hardware, not yours. What you actually need from a server is uptime, a stable IP, fast disk for session files and repositories, and enough RAM to run builds and test suites alongside the agent. A Netcup VPS delivers exactly that for the price of a couple of coffees per month, and with the coupon codes below the first month can be free.

This guide covers what Pi is, how its architecture works, how to use it day to day, a complete step-by-step Netcup deployment, and which cheap Netcup server tier fits which kind of Pi workload.

What is Pi?

Pi is an extensible AI agent that works from your terminal. It can inspect files, run commands, edit content and work through multi-step tasks — the usual agent repertoire — but the way it gets there is deliberately different from its competitors.

Pi is built by Earendil Inc. and released under the MIT License. It is written in TypeScript, distributed as @earendil-works/pi-coding-agent on npm, and has become one of the most-starred agent projects on GitHub, with well over a million npm downloads a week. Its second tagline — "Adapt Pi to your workflows, not the other way around" — is the whole product thesis.

Primitives Over Features

The default Pi agent ships with four tools: read, write, edit and bash. That is it. There is no built-in sub-agent system, no plan mode, no permission dialog, no web search tool baked into the core.

This is not an oversight. Those capabilities exist — as optional extensions. Sub-agents, plan mode and permission gates are all things you install if you want them, and leave out if you do not. The result is a core that stays small enough to read, debug and trust, and a context window that is not pre-loaded with tool definitions you never use.

Core Capabilities

Multi-provider model access Pi supports 15+ AI providers and hundreds of models out of the box: Anthropic, OpenAI, Google, Azure, Amazon Bedrock, Mistral, Groq and more. Switch with /model, cycle with Ctrl+P, save a default with Ctrl+S. Pricing, context limits and capabilities are shown inline in the selector.

Local and custom endpoints Pi integrates directly with the llama.cpp router for GGUF files via the /llama command. Ollama, LM Studio, vLLM and any OpenAI-compatible endpoint are added through a models.json entry. On a larger Netcup server this means you can run models locally and keep inference entirely on your own hardware.

Tree-structured sessions Every conversation is a JSONL file on disk where each entry has an ID and a parent. Any path through that tree is a branch. You can continue from an earlier message to create a new branch in the same file, fork selected history into a new session, or clone the active branch — and nothing is ever destroyed.

Context engineering Pi assembles its system prompt from base instructions plus discovered context files: AGENTS.md, CLAUDE.md, SYSTEM.md for a full system-prompt replacement, and APPEND_SYSTEM.md for additions. Compaction inserts a summary entry that replaces older messages in subsequent requests while leaving the original entries intact.

Real-time steering Pi distinguishes steering messages (which enter after the current turn) from follow-up messages (which enter after all pending work finishes). You can redirect a running agent without killing it.

Four interfaces Interactive TUI, --print mode for scripted text output, --mode json for a JSONL event stream, and --mode rpc for programmatic control — plus a TypeScript SDK for embedding Pi inside your own application.

Extensions, skills, prompts, themes Extensions are TypeScript modules that register commands, tools, event hooks, model providers and MCP servers. Skills are directories with a SKILL.md that load on demand. Prompt templates and themes round out the customization surface. All four can be bundled and shared as packages.

What Pi Deliberately Does Not Do

Pi does not ask for approval before every tool call, and it does not ship a built-in sandbox. It runs with the full permissions of the user account that started it. The documentation is blunt about this: "Safety comes from limiting the files, credentials, processes, and network services Pi can access."

This is precisely why a dedicated VPS is the right home for Pi. Instead of pointing an unsandboxed agent at your laptop — with your SSH keys, your password manager, your personal files and your production credentials all one bash call away — you give it a disposable server that contains only the repositories and short-lived tokens the task actually needs. A Netcup VPS at EUR 12.18/month is a cheap, rebuildable blast radius.

How to Use Pi

The Terminal UI

Pi runs fullscreen by default and splits into three areas: a transcript of prompts and responses, an editor for composing input, and a footer showing session metadata, context usage and accumulated cost. The editor border colour reflects the current thinking level, so you always know how hard the model is being asked to work.

Slash Commands

Type / to search the command palette. The ones you will use constantly:

Keybindings Worth Memorising

• Enter sends, Shift+Enter adds a newline
• Alt+Enter queues a follow-up to run after the current task
• Escape stops the current task
• Ctrl+G opens your external editor for long prompts
• Ctrl+O expands or collapses tool output
• Ctrl+T toggles thinking blocks
• Ctrl+X copies the last response
• Ctrl+L opens the model selector

Referencing Files and Running Shell Commands

Type @ to search and attach files, or use Tab for path completion. In terminals that support it, images can be pasted or dragged straight into the editor.

Prefix a line with ! to run a shell command and include its output in the conversation. Use !! to run a command without sharing the result with the model — handy for checking something privately mid-session.

Configuration Layout

Pi uses a two-tier configuration system. The agent directory defaults to ~/.pi/agent and can be moved with PI_CODING_AGENT_DIR:

~/.pi/agent/
  settings.json        # user preferences and resource paths
  keybindings.json     # custom keybindings
  mcp.json             # MCP servers available across projects
  models.json          # custom endpoints and model definitions
  auth.json            # saved API keys and OAuth credentials
  AGENTS.md            # user-wide instructions
  SYSTEM.md            # full system prompt replacement
  APPEND_SYSTEM.md     # appended instructions
  extensions/ skills/ prompts/ themes/

A project directory at .pi/ mirrors this structure for per-repository overrides, and loads only after you grant project trust. The trusted project file takes precedence over the corresponding agent-directory file.

Skills

A skill is a directory containing a SKILL.md with YAML frontmatter — name, description, license, compatibility, disable-model-invocation — plus any scripts, references and assets it needs.

At startup Pi scans the configured skill directories and adds each skill's name, description and path to the system prompt. The full instructions load only when the skill is actually needed, which keeps detailed guidance out of context until it matters. Skills are discovered in ~/.agents/skills/ and .agents/skills/, searched recursively, stopping at repository roots.

The guiding rule from the docs: "Use a skill when a workflow needs more context than a prompt template but does not need a new executable integration point."

Extensions

Extensions are TypeScript or JavaScript modules in ~/.pi/agent/extensions/. A minimal one looks like this:

export default function (pi: ExtensionAPI) {
  pi.registerCommand("hello", {
    description: "Show a greeting",
    handler: async (name, ctx) => {
      ctx.ui.notify(`Hello, ${name || "world"}!`, "info");
    },
  });
}

Load one directly during development with pi --extension ./hello.ts. Pi uses jiti to compile TypeScript with no build step.

Extensions register through pi.registerCommand(), pi.registerTool(), pi.registerProvider(), pi.registerMcpServer() and pi.on() for lifecycle events like session_start, before_agent_start, tool_call and message_end. Long-lived resources should start from session_start, not the factory function, because some invocations skip session initialisation.

Extensions run inside the Pi process with full OS permissions. Only load them from sources you trust.

Packages

A package bundles extensions, skills, prompts and themes into one distributable unit — an ordinary directory or npm package:

pi install npm:@example/[email protected]
pi install git:github.com/example/pi-tools@v1
pi install ./local-package
pi list
pi remove <source>
pi update --extensions

Test without installing using pi -e npm:@example/pi-tools. Publishers add the pi-package keyword to npm metadata for gallery discoverability.

Headless Modes for Automation

This is where a self-hosted Pi on a VPS earns its keep. Pi's non-interactive modes turn it into a scriptable component:

# Print mode: run prompts, write final text to stdout, exit
pi --print "Summarise the open TODOs in this repo"

# JSON mode: emit a JSONL event stream for parsing
pi --mode json "Run the test suite and report failures"

# RPC mode: read JSONL commands from stdin, stream responses out
pi --mode rpc

Useful flags for unattended runs:

Combine --print with -t and --approve in a cron job and your Netcup VPS becomes an autonomous maintenance worker: nightly dependency audits, changelog drafts, log triage, scheduled refactors.

How the Agent Loop Actually Works

Understanding the loop helps you debug and tune it:

1. Input — a submitted message joins the active conversation branch
2. Request building — Pi assembles the system prompt, the active branch, available tools and model settings
3. Response — the provider streams back text and tool calls
4. Tool execution — Pi records the response, executes each tool call, and records the results
5. Loop control — if more work is pending, another turn runs; otherwise the run completes

Tools and extensions execute inside the Pi process, using the operating-system permissions of that process. There is no separate sandbox layer unless you create one — which is exactly what the containerisation step in the quick start below does.

Quick Start Guide: Deploying Pi on a Netcup VPS

Step 1: Order Your Netcup Server

Go to netcup.com, choose the VPS 1000 G12.5 (4 vCore, 8 GB ECC RAM, 128 GB SSD, 2.5 Gbit/s), and during checkout apply a coupon:

6877nc17911959130
6877nc17913304870
6877nc17912005430

Pick a data centre close to you — Nürnberg, Vienna, Amsterdam, Manassas or Singapore — because TUI latency over SSH is what you will feel every day. Select a recent Ubuntu LTS or Debian image. Provisioning typically takes a few minutes, after which your credentials appear in the netcup Customer Control Panel.

If you prefer EUR 5 off any order instead of a free month, use 36nc17718015549.

Step 2: First Login and Server Hardening

Pi runs with your account's full permissions, so harden the box before installing it:

ssh root@your-server-ip

apt update && apt upgrade -y
adduser pi
usermod -aG sudo pi

# Copy your SSH key to the new user
rsync --archive --chown=pi:pi ~/.ssh /home/pi/

Disable password login and root SSH in /etc/ssh/sshd_config:

PermitRootLogin no
PasswordAuthentication no

Then restart SSH and enable the firewall:

systemctl restart ssh
ufw allow OpenSSH
ufw enable

Log back in as the pi user from here on. Netcup's out-of-band remote console in the control panel is your safety net if you ever lock yourself out.

Step 3: Install Node.js and Dependencies

Pi requires Node.js 22.19 or newer. Install it plus the tools Pi's bash tool expects:

sudo apt install -y curl git ripgrep ca-certificates tmux
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt install -y nodejs
node --version   # must report v22.19.0 or higher

Step 4: Install Pi

Pick one of three installation routes.

Install script (recommended):

curl -fsSL https://pi.dev/install.sh | sh

npm:

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

Nix:

nix profile add github:earendil-works/pi/stable

Verify the installation:

pi --version

Step 5: Authenticate and Pick a Model

Change into a working directory and launch the TUI:

mkdir -p ~/workspace && cd ~/workspace
pi

Inside Pi, run /login, choose your provider, and follow the prompts. Credentials are stored in ~/.pi/agent/auth.json.

For headless and CI use, skip stored credentials entirely and export the provider environment variable instead — Pi resolves credentials in the order --api-key flag, then auth.json, then the apiKey field in models.json, then environment variables or ambient cloud credentials:

echo 'export ANTHROPIC_API_KEY="sk-..."' >> ~/.bashrc
source ~/.bashrc

Then run /model to browse models filtered by working authentication. Ctrl+S saves your default; Ctrl+P cycles.

Step 6: Configure tmux So Pi Survives Disconnects

This is the single most valuable step for a remote server. Without tmux, a dropped SSH connection kills your agent mid-task.

tmux also needs extended keys enabled, otherwise it reports Shift+Enter, Ctrl+Enter and plain Enter as the same key. Add to ~/.tmux.conf (tmux 3.5+):

set -g extended-keys on
set -g extended-keys-format csi-u

On tmux 3.2–3.4, use only the first line. Restart the server and start a named session:

tmux kill-server
tmux new -s pi

Verify that Shift+Enter inserts newlines, Enter submits, and Alt+Enter queues follow-ups. Now detach with Ctrl+B D, close your laptop, and reattach later from anywhere:

tmux attach -t pi

Step 7: Set Up Project Context

Pi reads context files to understand your conventions. Create a user-wide ~/.pi/agent/AGENTS.md for things that are always true, and a per-repository AGENTS.md for project specifics:

cd ~/workspace/my-project
cat > AGENTS.md <<'EOF'
# Project conventions

- Package manager: pnpm
- Run tests with `pnpm test`, lint with `pnpm lint`
- Never commit directly to main; branch first
- Keep changes minimal and match surrounding style
EOF

Start Pi and reference files with @:

Review @src/auth.ts for session handling bugs and propose a fix.

Step 8: Containerise for a Real Sandbox

Because Pi has no built-in permission system, containerisation is the strongest practical isolation. On a VPS this is cheap insurance: the container protects host resources you have not explicitly exposed.

Install Docker and create Dockerfile.pi:

FROM node:24-bookworm-slim

RUN apt-get update \
  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep \
  && rm -rf /var/lib/apt/lists/*
RUN npm install -g --ignore-scripts @earendil-works/pi-coding-agent

WORKDIR /workspace
ENTRYPOINT ["pi"]

Build and run it:

docker build -t pi-sandbox -f Dockerfile.pi .

docker run --rm -it \
  -e ANTHROPIC_API_KEY \
  -v "$PWD:/workspace" \
  -v pi-agent-home:/root/.pi/agent \
  pi-sandbox

The $PWD:/workspace mount exposes only the current project. The named pi-agent-home volume keeps container-local settings, credentials and sessions between runs. Verify the boundary from inside Pi with !pwd — it should print /workspace. Do not mount your host ~/.pi/agent unless you specifically need the existing configuration.

Step 9: Add a Scheduled Agent Job

With Pi on an always-on Netcup VPS, you can schedule autonomous work. Add a cron entry:

crontab -e

0 3 * * * cd /home/pi/workspace/my-project && /usr/local/bin/pi --print --approve \
  -t read,bash "Check for outdated dependencies and write findings to AUDIT.md" \
  >> /home/pi/pi-cron.log 2>&1

Note the -t read,bash allowlist: the job can inspect and run commands but cannot write or edit arbitrary files. Scope tools to the minimum each job needs.

Step 10: Optional — Run Models Locally

On a larger Netcup server you can keep inference on your own hardware. Pi supports the llama.cpp router natively via /llama. For Ollama, LM Studio or vLLM, add them to ~/.pi/agent/models.json:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [{ "id": "qwen2.5-coder:7b" }]
    }
  }
}

The dummy API key satisfies Pi; Ollama ignores it. For authenticated endpoints, use $NAME environment-variable interpolation instead of literal values.

Step 11: Back Up Your Sessions

Sessions live in ~/.pi/agent/sessions/, organised by working directory. They are plain JSONL — easy to archive:

tar czf ~/pi-sessions-$(date +%F).tar.gz ~/.pi/agent/sessions

Pair this with netcup snapshots from the control panel for whole-server restore points before risky upgrades.

Choosing the Right Netcup Server for Pi Cheap Hosting

Pi's own resource footprint is modest — it is a Node.js process streaming tokens from a remote API. What actually consumes your server are the commands Pi runs: builds, test suites, Docker images, language servers, and, if you go local, model inference.

Here is how the current netcup VPS G12.5 line maps to Pi workloads.

VPS Comparison for Pi

All tiers include IPv4 + IPv6, a traffic flat rate, snapshots, DDoS protection, full root access and an out-of-band remote console. Locations: Nürnberg, Vienna, Amsterdam, Manassas, Singapore.

Recommended Configurations

VPS 1000 G12.5 — the default choice for Pi

4 vCores, 8 GB ECC RAM, 128 GB SSD at EUR 12.18/month. This runs Pi comfortably with a few repositories, ripgrep searches across large codebases, Node or Python test suites, and a tmux session you leave attached for weeks. If you use Anthropic, OpenAI or Google models, this is all the server Pi needs.

Coupons for 1 month free:

6877nc17911959135
6877nc17911959133
6877nc17911959132

VPS 2000 G12.5 — containerised and multi-project

8 vCores, 16 GB ECC RAM, 256 GB SSD at EUR 22.62/month. The right tier once you run Pi inside Docker sandboxes, keep multiple project containers warm, or run builds that genuinely use parallelism. 16 GB leaves headroom for a database and a language server next to the agent.

Coupons for 1 month free:

6878nc17911959164
6878nc17911959163
6878nc17911959162

VPS 4000 G12.5 — parallel Pi sessions and CI

12 vCores, 32 GB ECC RAM, 512 GB SSD at EUR 38.11/month. Run several independent Pi sessions against different branches, each in its own container, plus a CI runner on the same box. The 512 GB SSD absorbs Docker layer caches, node_modules trees and months of session JSONL without pruning.

Coupons for 1 month free:

6879nc17911959180
6879nc17912008310
6879nc17911959185

VPS 8000 G12.5 — team harness and local inference

16 vCores, 64 GB ECC RAM, 1 TB SSD at EUR 56.39/month. The top of the shared-core line. Enough RAM to serve mid-size GGUF models through llama.cpp or Ollama while several developers run their own Pi sessions over SSH, each with separate agent directories.

Coupons for 1 month free:

6880nc17911959200
6880nc17911959205
6880nc17911959204

Root Servers: Dedicated Cores for Predictable Agent Runs

If Pi is running test suites or compilations on a schedule, dedicated cores remove the variance of shared CPU. Netcup's Root Server G12.5 line uses AMD EPYC 9645 cores with NVMe storage.

RS 1000 G12.5 — EUR 18.26/month, 1 month free:

6874nc17911959062
6874nc17911959061
6874nc17911959060

RS 2000 G12.5 — EUR 34.20/month, 1 month free:

6875nc17911959085
6875nc17911959084
6875nc17911959083

RS 8000 G12.5 — EUR 124.72/month, 1 month free:

6876nc17911959104
6876nc17911959103
6876nc17911959102

How to Decide

Start with the VPS 1000 G12.5. Pi's agent process is small; the server exists to run your toolchain. Upgrade only when you hit a real wall:

• Out of RAM during builds — move to VPS 2000 G12.5
• Builds feel inconsistent at peak hours — move to a Root Server for dedicated cores
• Running more than two or three concurrent Pi containers — move to VPS 4000 G12.5
• Serving local GGUF models through /llama — go straight to VPS 8000 G12.5 or RS 8000 G12.5, where RAM is the binding constraint

Disk sizing. Session JSONL files are tiny. What grows is Docker layers, dependency caches and cloned repositories. 128 GB is generous for a handful of projects; if you mirror large monorepos, step up a tier or add netcup Local Block Storage.

Location. Pick the data centre nearest you. The Pi TUI is interactive and every keystroke crosses the network — 20 ms feels instant, 200 ms does not.

Cost Optimisation

1. Apply a coupon on every first order. A free month on a VPS 2000 G12.5 is EUR 22.62 you keep.
2. Use hourly billing for experiments. Spin a server up, test a Pi extension, destroy it.
3. Commit to 12 months for the lowest monthly rate once your setup has settled.
4. Start small and scale up. Netcup makes upgrading straightforward; over-provisioning on day one is wasted money.
5. Stack 36nc17718015548 for EUR 5 off any order when a free-month coupon does not apply to your chosen tier.

Coupon Summary

More current codes are always listed on netcup.best.

Conclusion

Pi is the agent harness for people who want to understand and control their tooling. A four-tool core, a documented agent loop, sessions as readable JSONL trees, and an extension API that lets you add exactly the capabilities you need — sub-agents, plan mode, permission gates — rather than inheriting someone else's defaults. It is MIT licensed, installs in one command, and speaks to 15+ model providers plus any local endpoint you point it at.

That same minimalism carries a trade-off Pi states openly: no built-in sandbox, no per-call approval, full user permissions. Running it on your personal machine means handing an LLM-driven bash tool the keys to everything you own.

Self-hosting Pi on a Netcup VPS resolves that cleanly. A dedicated server is a controlled blast radius — it holds only the repositories and short-lived credentials a task actually requires, it can be snapshotted before anything risky, and it can be rebuilt from scratch in minutes if something goes wrong. Add Docker containerisation on top and you have the isolation Pi deliberately leaves to the operator.

The practical benefits stack up fast:

• Always on. Launch a long refactor inside tmux, close your laptop, reattach from your phone tomorrow.
• Genuinely isolated. The agent touches a disposable server, not your personal filesystem, SSH keys or password manager.
• Automatable. --print, --mode json and --mode rpc plus cron turn your VPS into an autonomous maintenance worker that scopes its own tool access.
• Fast and close to your data. 2.5 Gbit/s with a traffic flat rate, NVMe or SSD storage, and five data centre locations.
• Recoverable. Snapshots, an out-of-band remote console and full root access mean no lockout is permanent.
• Private by default. With a local llama.cpp or Ollama endpoint on a larger tier, your code never leaves infrastructure you control.

And it is cheap. A VPS 1000 G12.5 at EUR 12.18/month runs Pi, your toolchain and your repositories with room to spare — far less than a single month of most hosted AI development platforms, and you own the whole stack. With a coupon, the first month costs nothing:

6877nc17913304870
6877nc17912005430
6877nc17911959135

Pi's promise is that the harness is yours. Put it on a server that is yours too.