@capsuleer/bun

Shell execution and network fetch for Capsuleer agents. Exposes Bun's $ tagged template shell and fetch as globals — so agents can run commands, call APIs, and pipe results with native Bun performance.

capsuleer install bun

Built-in — ships with every Capsuleer environment. Shell access is subject to the shell policy.

API

Shell execution ($)

$ is Bun's tagged template shell, exposed as a global. Use it to run any shell command:

// Run a command and get its output
const result = await $`git log --oneline -10`
console.log(result.text())

// Check exit code
const test = await $`bun test`.quiet()
if (test.exitCode !== 0) throw new Error("Tests failed")

// Pipe commands
const count = await $`find . -name "*.ts" | wc -l`
console.log(count.text().trim())

// Interpolate values safely (auto-escaped)
const branch = "main"
const log = await $`git log ${branch} --oneline -5`

$ throws on non-zero exit by default. Use .quiet() to suppress output, .nothrow() to suppress the throw.

Network fetch (fetch)

Standard fetch API, available as a global:

// GET request
const res = await fetch("https://api.github.com/repos/arclabs/axon")
const repo = await res.json()

// POST with JSON body
const res = await fetch("https://api.example.com/deploy", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": `Bearer ${process.env.API_TOKEN}`
  },
  body: JSON.stringify({ ref: "main" })
})

Globals registered

| Global | Type | Description | |--------|------|-------------| | $ | BunShell | Tagged template shell — await $\cmd`| |fetch|fetch| Native Bun fetch — same asglobalThis.fetch` |

Both are also available via the bun namespace: bun.$, bun.fetch.

Policy

Shell access is controlled by the shell policy. When denied, any use of $ emits policy:denied and throws:

const capsule = await Capsule({
  policy: {
    shell: false,        // block all shell commands
    shell: true,         // allow all
    shell: "escalate",   // pause and ask before each command
    network: {
      fetch: { allow: ["https://api.github.com/**"], deny: ["**"] }
    }
  }
})

See the policy docs for the full rule syntax.