Building pi extensions

Build a pi extension that gives the agent computer-management tools and transparently routes every bash call to a Vers computer — so the agent acts on a remote machine without knowing it.

This direct API example uses retained v1 wire names such as /vm, vm_id, and vm_exec. Those are protocol and example identifiers; the product resource is called a computer.

What you’ll build

An extension that registers create_vm, vm_exec, vm_use, vm_local, and an overridden bash tool
A transparent routing pattern that generalizes to containers, cloud VMs, SSH hosts, or any remote execution target
Time: ~20 minutes — mostly reading, ~80 lines to write

Prerequisites

pi coding agent installed
Vers account with VERS_API_KEY set in your environment
ssh and openssl on your PATH

Step 1: Create the Extension

Create ~/.pi/agent/extensions/my-vers.ts:

// ~/.pi/agent/extensions/my-vers.ts
import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
import { Type } from "@sinclair/typebox";
import { execFile } from "node:child_process";
import { writeFile } from "node:fs/promises";

export default function myVersExtension(pi: ExtensionAPI) {
  const API_KEY = process.env.VERS_API_KEY || "";
  const BASE = "https://api.vers.sh/api/v1";
  let activeVmId: string | undefined;

  async function versApi(method: string, path: string, body?: unknown) {
    const res = await fetch(`${BASE}${path}`, {
      method,
      headers: { "Content-Type": "application/json", Authorization: `Bearer ${API_KEY}` },
      body: body ? JSON.stringify(body) : undefined,
    });
    if (!res.ok) throw new Error(`Vers API ${res.status}: ${await res.text()}`);
    return res.headers.get("content-type")?.includes("json") ? res.json() : undefined;
  }

  // We'll add tools in the next steps
}

Test it loads: run pi -e ~/.pi/agent/extensions/my-vers.ts. Pi should start with no errors.

Step 2: Add Computer Creation

Add this inside the myVersExtension function:

  pi.registerTool({
    name: "create_vm",
    label: "Create Computer",
    description: "Create a new Vers computer and wait for it to boot",
    parameters: Type.Object({}),
    async execute() {
      const r = await versApi("POST", "/vm/new_root?wait_boot=true", {
        vm_config: { mem_size_mib: 4096, fs_size_mib: 8192 },
      });
      return { content: [{ type: "text", text: `Computer created: ${r.vm_id}` }] };
    },
  });

Reload pi (/reload in the TUI). Ask the agent to create a computer — it calls your tool and returns a computer ID.

Step 3: Add SSH Execution

Vers computers use SSH over TLS on port 443. Add the SSH helper and a tool:

  async function getKeyPath(vmId: string): Promise<string> {
    const info = await versApi("GET", `/vm/${vmId}/ssh_key`);
    const path = `/tmp/vers-${vmId.slice(0, 12)}.pem`;
    await writeFile(path, info.ssh_private_key, { mode: 0o600 });
    return path;
  }

  function sshExec(keyPath: string, vmId: string, command: string): Promise<string> {
    return new Promise((resolve, reject) => {
      execFile("ssh", [
        "-i", keyPath,
        "-o", "StrictHostKeyChecking=no",
        "-o", "UserKnownHostsFile=/dev/null",
        "-o", "LogLevel=ERROR",
        "-o", `ProxyCommand=openssl s_client -connect %h:443 -servername %h -verify_hostname %h -verify_return_error -quiet 2>/dev/null`,
        `root@${vmId}.vm.vers.sh`,
        command,
      ], (err, stdout, stderr) => {
        if (err) reject(new Error(stderr || err.message));
        else resolve(stdout);
      });
    });
  }

  pi.registerTool({
    name: "vm_exec",
    label: "Run on Computer",
    description: "Execute a command on a Vers computer via SSH",
    parameters: Type.Object({
      vmId: Type.String({ description: "Computer ID" }),
      command: Type.String({ description: "Shell command" }),
    }),
    async execute(_id, params) {
      const key = await getKeyPath(params.vmId);
      const out = await sshExec(key, params.vmId, params.command);
      return { content: [{ type: "text", text: out || "(no output)" }] };
    },
  });

Reload. Ask the agent to create a computer then run uname -a on it. You’ll see the computer’s kernel info.

The SSH connection uses openssl s_client as a ProxyCommand to tunnel through TLS on port 443. This is how Vers exposes SSH without opening additional ports.

Step 4: Override bash for Transparent Routing

This is the key pattern. Instead of making the LLM use vm_exec, override the built-in bash so normal commands route to the computer automatically:

  pi.registerTool({
    name: "vm_use",
    label: "Use Computer",
    description: "Route all bash commands to this computer. Use vm_local to switch back.",
    parameters: Type.Object({ vmId: Type.String({ description: "Computer ID" }) }),
    async execute(_id, params, _s, _u, ctx) {
      activeVmId = params.vmId;
      ctx.ui.setStatus("vers", `vers: ${params.vmId.slice(0, 12)}`);
      return { content: [{ type: "text", text: `Routing to ${params.vmId}` }] };
    },
  });

  pi.registerTool({
    name: "vm_local",
    label: "Use Local",
    description: "Stop routing to the computer and run commands locally",
    parameters: Type.Object({}),
    async execute(_id, _p, _s, _u, ctx) {
      activeVmId = undefined;
      ctx.ui.setStatus("vers", undefined);
      return { content: [{ type: "text", text: "Back to local" }] };
    },
  });

  pi.registerTool({
    name: "bash",
    label: "bash",
    description: "Execute a bash command. Routes to the active computer if set, otherwise runs locally.",
    parameters: Type.Object({
      command: Type.String({ description: "Command to execute" }),
      timeout: Type.Optional(Type.Number({ description: "Timeout in seconds" })),
    }),
    async execute(_id, params) {
      if (!activeVmId) {
        return new Promise((resolve) => {
          execFile("bash", ["-c", params.command], (err, stdout, stderr) => {
            const out = (stdout || "") + (stderr || "");
            if (err) resolve({ content: [{ type: "text", text: `${out}\nExit: ${err.code}` }] });
            else resolve({ content: [{ type: "text", text: out || "(no output)" }] });
          });
        });
      }
      const key = await getKeyPath(activeVmId);
      const out = await sshExec(key, activeVmId, params.command);
      return { content: [{ type: "text", text: out || "(no output)" }] };
    },
  });

Reload. Now:

Ask the agent to create a computer
Ask it to vm_use that computer
Ask it to install Node.js — it runs apt-get install nodejs over SSH without the LLM knowing

The LLM calls bash as usual. Your extension decides where it runs.

Step 5: Add Status on Startup

Show the computer count in the footer when pi starts:

  pi.on("session_start", async (_ev, ctx) => {
    try {
      const vms = await versApi("GET", "/vms");
      ctx.ui.setStatus("vers", `vers: ${vms.length} computer(s)`);
    } catch {
      ctx.ui.setStatus("vers", "vers: offline");
    }
  });

Reload. You’ll see “vers: N computer(s)” in the footer.

The Complete Extension

The full file is ~80 lines of logic. Copy it from the assembled steps above, or see the production version with all four tool overrides (bash, read, edit, write) plus branching, commits, and SCP at hdresearch/pi-v.

Key Patterns

Tool override routing

LLM calls bash → extension checks activeVmId → SSH or local

The LLM doesn’t need to know about routing. It calls the same tools regardless. This pattern works for any remote execution target — containers, cloud VMs, SSH hosts.

API client as closure

The versApi function, activeVmId state, and SSH helpers all live in the extension’s closure. Multiple tools share them. No global state, no classes — just functions and variables scoped to the extension.

Status feedback

ctx.ui.setStatus shows persistent info in the footer. ctx.ui.setWidget shows multi-line info above the editor. Use these to keep the user informed without interrupting the agent.

What’s next

Vers CLI

The supported command-line surface for remote computers.

Full pi-v extension

Production version: read/edit/write overrides, commits, branches, SCP.

Shell authentication

Create an API key through the terminal-oriented authentication flow.

Vers overview

The product model behind the API.

Introduction

Get running

API-driven guides

Building pi extensions

What you’ll build

Prerequisites

Step 1: Create the Extension

Step 2: Add Computer Creation

Step 3: Add SSH Execution

Step 4: Override bash for Transparent Routing

Step 5: Add Status on Startup

The Complete Extension

Key Patterns

Tool override routing

API client as closure

Status feedback

What’s next

Vers CLI

Full pi-v extension

Shell authentication

Vers overview

​What you’ll build

​Prerequisites

​Step 1: Create the Extension

​Step 2: Add Computer Creation

​Step 3: Add SSH Execution

​Step 4: Override bash for Transparent Routing

​Step 5: Add Status on Startup

​The Complete Extension

​Key Patterns

​Tool override routing

​API client as closure

​Status feedback

​What’s next

Vers CLI

Full pi-v extension

Shell authentication

Vers overview

What you’ll build

Prerequisites

Step 1: Create the Extension

Step 2: Add Computer Creation

Step 3: Add SSH Execution

Step 4: Override bash for Transparent Routing

Step 5: Add Status on Startup

The Complete Extension

Key Patterns

Tool override routing

API client as closure

Status feedback

What’s next