@clankie/sandbox

Gondolin micro-VM sandbox for clankie — runs agent tools inside an isolated VM with network policies, secret injection, and filesystem isolation

Package details

← Back
extensionskill

Install @clankie/sandbox from npm and Pi will load the resources declared by the package manifest.

npm report
$ pi install npm:@clankie/sandbox
Package
@clankie/sandbox
Version
0.5.0
Published
Mar 11, 2026
Downloads
27/mo · 12/wk
Author
thiagovarela
License
MIT
Types
extension, skill
Size
11.9 KB
Dependencies
1 dependency · 2 peers
Pi manifest JSON
{
  "extensions": [
    "./src/index.ts"
  ],
  "skills": [
    "./skills"
  ]
}

Security note

Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.

README

@clankie/sandbox

Runs bash commands inside a Gondolin micro-VM. Transparent — just turn it on and all shell execution is sandboxed.

Note While some @clankie extensions may work with a bare pi installation, they are crafted to be used with clankie (built on top of pi).

File tools (read/write/edit) stay on the host as-is — workspace-jail handles those. The workspace is mounted into the VM via VFS, so bash commands see the same files.

Setup

Requires QEMU (Linux) or libkrun (macOS Apple Silicon).

// ~/.clankie/clankie.json
{ "sandbox": { "enabled": true } }

That's it. Every bash tool call and ! command now runs inside a VM.

Optional: network policy

By default the VM can reach any host. A built-in safety blocklist blocks cloud metadata endpoints (169.254.169.254, etc.).

{
  "sandbox": {
    "enabled": true,
    "network": {
      // Block additional hosts
      "blockedHosts": ["*.internal.corp.net"],

      // Inject secrets into the HTTP layer
      "secrets": {
        "API_KEY": "sk-...",
        "SCOPED_KEY": { "value": "token", "hosts": ["api.example.com"] }
      },

      // Or go strict: only these hosts are reachable
      // "mode": "allowlist",
      // "allowedHosts": ["api.openai.com", "*.github.com"]
    }
  }
}