|
| 1 | +# pi-enclave |
| 2 | + |
| 3 | +> From [yapp](https://github.com/mgabor3141/yapp) · yet another pi pack |
| 4 | +
|
| 5 | +VM-isolated enclave for [pi](https://pi.dev). Runs all tools inside a [Gondolin](https://github.com/earendil-works/gondolin) micro-VM so secrets never enter the agent's execution environment. |
| 6 | + |
| 7 | +```bash |
| 8 | +pi install npm:pi-enclave |
| 9 | +``` |
| 10 | + |
| 11 | +Requires QEMU: `brew install qemu` (macOS) or `sudo apt install qemu-system-aarch64` (Linux). |
| 12 | + |
| 13 | +## How it works |
| 14 | + |
| 15 | +pi-enclave starts an Alpine Linux micro-VM (QEMU/aarch64) and redirects all tool execution into it. Your workspace is mounted read-write at the same path inside the VM, so tools see identical paths on host and guest. File changes are bidirectional. |
| 16 | + |
| 17 | +The core security property: **secrets never enter the VM**. Secrets configured in your TOML config (like `gh auth token`) are resolved on the host, and their values are replaced with random placeholders inside the VM. Gondolin's HTTP proxy substitutes real values on the wire, only for requests to configured hosts. |
| 18 | + |
| 19 | +``` |
| 20 | +┌──────────────────────────────────────────────────┐ |
| 21 | +│ Gondolin VM (Alpine Linux) │ |
| 22 | +│ │ |
| 23 | +│ /home/user/project ← bidirectional mount │ |
| 24 | +│ GH_TOKEN = "GONDOLIN_SECRET_a8f3..." (placeholder)│ |
| 25 | +│ All pi tools execute here │ |
| 26 | +└────────────────────┬─────────────────────────────┘ |
| 27 | + │ HTTP |
| 28 | + ▼ |
| 29 | +┌──────────────────────────────────────────────────┐ |
| 30 | +│ HTTP proxy (host-side) │ |
| 31 | +│ placeholder → real value (only for allowed hosts)│ |
| 32 | +└──────────────────────────────────────────────────┘ |
| 33 | +``` |
| 34 | + |
| 35 | +## Getting started |
| 36 | + |
| 37 | +``` |
| 38 | +/enclave init |
| 39 | +``` |
| 40 | + |
| 41 | +This creates: |
| 42 | +- `~/.pi/agent/extensions/pi-enclave.toml` — global config (env vars, base packages) |
| 43 | +- `~/.pi/agent/extensions/pi-enclave.d/` — drop-in files (git, jj, GitHub) |
| 44 | +- `.pi/enclave.toml` — project config with `enabled = true` |
| 45 | + |
| 46 | +Once enabled, all tools (bash, read, write, edit) execute inside the VM automatically. |
| 47 | + |
| 48 | +## Drop-in files |
| 49 | + |
| 50 | +Service integrations live in `pi-enclave.d/` as self-contained TOML files. Each can contribute packages, setup scripts, secrets, and host policies. Delete a file to disable that integration. |
| 51 | + |
| 52 | +``` |
| 53 | +~/.pi/agent/extensions/ |
| 54 | +├── pi-enclave.toml # base config: curl, jq, env vars |
| 55 | +└── pi-enclave.d/ |
| 56 | + ├── git.toml # git + user identity |
| 57 | + ├── github.toml # github-cli + secrets + policies |
| 58 | + └── jj.toml # jujutsu + user identity |
| 59 | +``` |
| 60 | + |
| 61 | +Example drop-in (`git.toml`): |
| 62 | + |
| 63 | +```toml |
| 64 | +packages = ["git"] |
| 65 | +setup = """ |
| 66 | +git config --global safe.directory '*' |
| 67 | +git config --global user.name "$USER_NAME" |
| 68 | +git config --global user.email "$USER_EMAIL" |
| 69 | +""" |
| 70 | +``` |
| 71 | + |
| 72 | +`USER_NAME` and `USER_EMAIL` are defined in the main config as env vars resolved from the host: |
| 73 | + |
| 74 | +```toml |
| 75 | +[env] |
| 76 | +USER_NAME = { command = "git config --global user.name" } |
| 77 | +USER_EMAIL = { command = "git config --global user.email" } |
| 78 | +``` |
| 79 | + |
| 80 | +## Configuration |
| 81 | + |
| 82 | +### Env vars |
| 83 | + |
| 84 | +Non-secret values available in the VM and setup scripts. Three source types: |
| 85 | + |
| 86 | +```toml |
| 87 | +[env] |
| 88 | +EDITOR = "vim" # static |
| 89 | +USER_NAME = { command = "git config user.name" } # host command |
| 90 | +GOPATH = { env = "GOPATH" } # host env var |
| 91 | +``` |
| 92 | + |
| 93 | +### Secrets |
| 94 | + |
| 95 | +Like env vars, but values never enter the VM. The HTTP proxy injects them on the wire. |
| 96 | + |
| 97 | +```toml |
| 98 | +[secrets.GH_TOKEN] |
| 99 | +command = "gh auth token" |
| 100 | +hosts = ["api.github.com", "github.com", "*.githubusercontent.com"] |
| 101 | +``` |
| 102 | + |
| 103 | +### Git credentials |
| 104 | + |
| 105 | +Configures git credential helpers using secret placeholders: |
| 106 | + |
| 107 | +```toml |
| 108 | +[[git-credentials]] |
| 109 | +host = "github.com" |
| 110 | +username = "x-access-token" |
| 111 | +secret = "GH_TOKEN" |
| 112 | +``` |
| 113 | + |
| 114 | +### Host policies |
| 115 | + |
| 116 | +Access control per host. `unmatched` determines what happens to requests that don't match any allow/deny rule. |
| 117 | + |
| 118 | +```toml |
| 119 | +[hosts."api.github.com"] |
| 120 | +unmatched = "prompt" |
| 121 | +allow.GET = ["/**"] |
| 122 | + |
| 123 | +[hosts."api.github.com".graphql] |
| 124 | +endpoint = "/graphql" |
| 125 | +allow.query = ["*"] |
| 126 | +allow.mutation = ["createPullRequest", "createIssue", "addComment"] |
| 127 | +``` |
| 128 | + |
| 129 | +GraphQL policy parses the request body and checks actual field names (not the spoofable operation name). |
| 130 | + |
| 131 | +### Mounts |
| 132 | + |
| 133 | +Additional directories to mount in the VM (e.g. for jj workspaces): |
| 134 | + |
| 135 | +```toml |
| 136 | +[[mounts]] |
| 137 | +path = "~/dev/myproject/.jj" |
| 138 | +``` |
| 139 | + |
| 140 | +### Project overrides |
| 141 | + |
| 142 | +Project configs override global. Packages accumulate; secrets, hosts, and env merge by key (later wins). |
| 143 | + |
| 144 | +```toml |
| 145 | +# .pi/enclave.toml — allow all GitHub operations in this project |
| 146 | +enabled = true |
| 147 | + |
| 148 | +[hosts."api.github.com"] |
| 149 | +unmatched = "allow" |
| 150 | +``` |
| 151 | + |
| 152 | +## Commands |
| 153 | + |
| 154 | +| Command | Description | |
| 155 | +|---------|-------------| |
| 156 | +| `/enclave` or `/enclave status` | Show VM state, packages, secrets | |
| 157 | +| `/enclave init` | Create project and global config files, enable enclave | |
| 158 | +| `/enclave on` | Enable VM isolation for this session | |
| 159 | +| `/enclave off` | Disable VM isolation for this session (shuts down VM) | |
| 160 | +| `/enclave restart` | Restart VM on next tool use | |
| 161 | +| `/enclave add <package>` | Search for and install an Alpine package | |
0 commit comments