Knowledge, Context and Agentic Engineering for Knowledge Work
← Module 04 · Agentic Engineering

Pi with a local model introduction

This tutorial introduces Pi as an open-source AI harness with explicit provider configuration. It separates the harness source, the provider endpoint and evidence that model inference runs locally.

Sources and product details checked 25 August 2026

Use a disposable practice repository without confidential files.Keep the first task within an explicit read-only tool allowlist.

Harness source, provider endpoint and inference location are three separate facts.

Step 1

Identify the harness and the three verification boundaries

Pi is an MIT-licensed AI harness whose model provider is configured separately. A local Pi process establishes the harness location. Local model inference additionally requires a local endpoint and observable local execution.

  1. Verify the harness source and installed package version.
  2. Identify the selected provider and its endpoint.
  3. Observe the process or service that performs inference.
  4. Keep the model licence and capability assessment separate from the harness licence.

Check: you can state which evidence supports the harness source, provider route and inference location.

Official Pi documentation · Official repository

The local-model route needs a harness runtime, a configured model service and a known repository state.

Step 2

Prepare the workspace and model service

  1. Use a disposable Git repository without confidential files or credentials.
  2. Confirm the current runtime requirements in the Pi documentation before installation.
  3. Start the chosen local model service and record its loopback endpoint when local inference is intended.
  4. Run git status --short outside Pi and preserve the starting state.

Check: the workspace, runtime, model endpoint and Git baseline are each available before Pi starts.

Prerequisites checked 25 August 2026 against the official Pi documentation.

The installation closes with the package source and installed version recorded together.

Step 3

Install Pi from the current maintained package

  1. Compare the package namespace with the current official repository and documentation.
  2. Install with npm install -g --ignore-scripts @earendil-works/pi-coding-agent.
  3. Open a new terminal when the executable is not yet visible in the current shell.
  4. Run pi --version and record the result beside the source check date.

Check: the installed executable reports a version and its package route matches the maintained Pi source.

Package namespace and command checked 25 August 2026 against the official repository.

A local provider claim requires a loopback endpoint and an observable local model process.

Step 4

Confirm the workspace, provider and inference route

  1. Start Pi in the intended repository and confirm its current working directory.
  2. Inspect the configured provider, model and endpoint before the first prompt.
  3. Use the documented llama.cpp router bound to 127.0.0.1 or the maintained Ollama integration for a local route.
  4. Observe the local model process or service log while a request runs. Record any remote connection that appears.

Check: the visible endpoint and observed process state support the claimed inference location.

Official llama.cpp integration · Official Ollama integration

Pi reads hierarchical project instructions and supports an explicit same-level override.

Step 5

Inspect the instruction hierarchy and overrides

Pi reads hierarchical AGENTS.md files and can also use CLAUDE.md. An AGENTS.override.md replaces the instruction file on the same directory level.

  1. Locate instruction files from the project root towards the current working directory.
  2. Identify each file's directory scope and the rules that reach the current task.
  3. Check whether an AGENTS.override.md replaces the ordinary file on its level.
  4. Resolve contradictory instructions before exposing any write-capable tool.

Check: you can name the effective instruction files and explain any active override.

Instruction loading checked 25 August 2026 in the official usage documentation.

Pi relies on operating-system rights and explicit tool scope; project trust governs resource loading.

Step 6

Apply an explicit read-only tool allowlist

Pi runs with the operating-system rights of the user who starts it. Pi provides no built-in execution sandbox. Project trust governs whether project resources load, while exposed tool actions continue under the user's operating-system rights.

  1. Expose only read, grep, find and ls for the first task.
  2. Review the effect of every additional tool before adding it to the allowlist.
  3. Use a container or a restricted operating-system account when the task requires a stronger execution boundary.
  4. Keep credentials and confidential files outside the practice workspace.

Check: the active tools support repository inspection and provide no file-writing or shell-execution route.

Official Pi security documentation, checked 25 August 2026.

Pi keeps a small built-in surface and places additional behaviour in user-controlled adaptation.

Step 7

Locate extensions and the intentionally omitted built-ins

Pi supports Skills, extensions and packages. Built-in permission prompts, Plan Mode, Model Context Protocol support and Subagents are absent from the core product.

  1. Inspect the source and tool exposure of an extension before loading it.
  2. Use Skills for maintained procedures whose triggers and checks are explicit.
  3. Use separate processes and isolated workspaces when independent work should proceed in parallel.
  4. Add allowlists, containers or extensions only for a defined capability requirement.

Check: every added capability has a known source, tool scope and verification method.

Product boundaries checked 25 August 2026 in the official usage documentation.

The final check records separate evidence for source, endpoint, inference and repository state.

Step 8

Run one reversible orientation and verify each boundary

Start Pi with an explicit read-only tool allowlist and ask for a repository orientation whose claims can be checked directly.

  1. Run pi --tools read,grep,find,ls -p "Summarize this repository and explain how its checks are run.".
  2. Compare the answer with the cited instruction files and check definitions.
  3. Record the Pi source and version, configured provider endpoint and observed model process as separate evidence.
  4. Run git status --short outside Pi and compare it with the starting state.

Check: the orientation is source-grounded, local-inference evidence is explicit and the repository remains unchanged.

Pi documentation · Security boundary · sources checked 25 August 2026