homelab/active/software_pi/pi.md

Pi AI Harness

Prereqs

I would recommend using pass to store your api key. This is installed with dnf install pass on Fedora systems.

After installing pass, update your ~/.gnupg/gpg-agent.conf to set the timeout to max so automated processes can use the values in your password store:

default-cache-ttl 2147483647
max-cache-ttl 2147483647

Then add a pass.sh to you ~/.bashrc.d that looks like

pass unlock

That way every time you log in your pass keyring is unlocked for your session so automations can use it.

Setup

This is my ~/.pi/agent/models.json

{
  "providers": {
    "reeseapps-aipi": {
      "baseUrl": "https://aipi.reeseapps.com/v1",
      "api": "openai-completions",
      "apiKey": "!pass aipi/dev-token",
      "models": [
        {
          "id": "juggernaut",
          "input": ["text", "image"],
          "reasoning": true,
          "contextWindow": 262144,
          "maxTokens": 32768,
          "thinkingLevelMap": {
            "off": "none",
            "minimal": null,
            "low": "low",
            "medium": "medium",
            "high": null,
            "xhigh": "xhigh",
            "max": null
          }
        },
        {
          "id": "turbo",
          "input": ["text", "image"],
          "reasoning": true,
          "contextWindow": 262144,
          "maxTokens": 32768,
           "thinkingLevelMap": {
            "off": "none",
            "minimal": null,
            "low": "low",
            "medium": "medium",
            "high": null,
            "xhigh": "xhigh",
            "max": null
          }
        }
      ]
    }
  }
}

This is my ~/.pi/agent/settings.json

{
  "lastChangelogVersion": "1.3.0",
  "theme": "dark/dark",
  "defaultProvider": "reeseapps-aipi",
  "defaultModel": "turbo",
  "httpIdleTimeoutMs": 0,
  "enableInstallTelemetry": false,
  "doubleEscapeAction": "tree",
  "images": {
    "autoResize": false
  },
  "editorPaddingX": 0,
  "defaultThinkingLevel": "xhigh",
  "hideThinkingBlock": false,
  "thinkingBudgets": {
    "minimal": 1024,
    "low": 4096,
    "medium": 10240,
    "xhigh": 65536
  },
  "steeringMode": "all"
}

Installing for sysadmin work

I would absolutely recommend installing pi under a special user (I call mine ops) with limited sudoers access that you tightly control. Pair that with the following AGENTS.md at /home/ops/AGENTS.md:

# AGENTS.md

## Sudo policy

The `ops` user on this machine has **limited sudoers capabilities**. The exact
allowlist is discoverable at any time with:

sudo -l

Allowed (NOPASSWD) commands currently include: `hostnamectl hostname`, `reboot`,
`dnf update/upgrade/install/remove/clean/makecache/autoremove`,
`dnf config-manager addrepo`, `systemctl start/restart/reload/enable`,
`firewall-cmd`, the ansible shim, `qemu-img`, `virsh`, `virt-install`,
`composer-cli`, `getfacl`, specific `setfacl` invocations,
`/usr/local/sbin/osbuild-auto.sh`, and `btrfs scrub`.

## Rule for agents

If you (the agent) believe you need a permission that is **not** in the
`sudo -l` allowlist — i.e., a command fails with a sudo permission error, or a
task requires root access you do not have — you must:

1. **Stop** and do not attempt workarounds that bypass sudo (no password
   guessing, no escalating via other users, no trying to write to root-owned
   paths without permission).
2. **Ask the human** to update sudoers with the specific command(s) you need,
   stating exactly which command(s) and arguments should be added so the user
   can review and approve them. Requests must be correct and copy-pastable,
   using full command paths in standard sudoers format, e.g.
   `ops ALL=(root) NOPASSWD: /usr/sbin/btrfs scrub*`

Do not proceed with root-only operations until the user has confirmed the
sudoers entries have been added.