Use with Claude Code

Claude Code can build, test, and deploy on a real server without touching your machine. Two integration modes — pick the one that fits your workflow.

CLI mode — the simple path

Claude Code already has Bash access. Point it at Gibil and it works immediately:

gibil create --name claude-task --repo https://github.com/you/project --json --ttl 30
gibil run claude-task "cd /root/project && pnpm install && pnpm test" --json
gibil destroy claude-task --json

The --json flag gives Claude structured output it can parse without regex:

{
  "stdout": "✓ 53 tests passing\n",
  "stderr": "",
  "exit_code": 0
}

MCP mode — the power path

MCP gives Claude typed tools instead of shell strings. No quoting hell, no escaping — Claude calls vm_write({ path: "src/app.ts", content: "..." }) and the MCP server handles SSH internally.

Your machine                              Hetzner VM
┌───────────────────────────────┐         ┌──────────────────┐
│  Claude Code                  │         │  /root/project/  │
│       │                       │   SSH   │  Node, Docker    │
│       ▼                       │         │                  │
│  gibil MCP server             │────────►│  Runs commands   │
│  vm_bash / vm_read / vm_write │◄────────│  Returns output  │
└───────────────────────────────┘         └──────────────────┘

Setup

Create a VM:

gibil create --name my-work --repo https://github.com/you/project --ttl 60

Add to Claude Code's MCP config (.claude/settings.json):

{
  "mcpServers": {
    "gibil": {
      "command": "gibil",
      "args": ["mcp", "my-work"]
    }
  }
}

Claude now has these tools:

Tool	What it does	Example
`vm_bash`	Run shell commands	`vm_bash({ command: "pnpm test" })`
`vm_read`	Read files	`vm_read({ path: "src/app.ts" })`
`vm_write`	Write files	`vm_write({ path: "src/app.ts", content: "..." })`
`vm_ls`	List directories	`vm_ls({ path: "src/" })`
`vm_grep`	Search file contents	`vm_grep({ pattern: "TODO", path: "src/" })`

MCP mode requires Claude Code with an active Max subscription. The MCP server runs locally and bridges to the VM over SSH.

Best practices

Set short TTLs — use --ttl 15 or --ttl 30 for task-scoped work
Always use --json — structured output is easier for Claude to parse
One VM per task — don't reuse VMs across unrelated work
Destroy when done — always clean up, even if the task fails

Next steps

AI Agent Sandbox — patterns for autonomous agents
Remote PR Workflow — push branches and open PRs from VMs
CLI Reference — full command documentation