gibil

Gibil

The box. Forged in seconds. Gone when done.

Your own machine, on demand. Root, Docker, SSH, your repo — ready in one command.
Forge for 30 minutes, 30 days, or anywhere in between. You set the timer.

The Problem

Your code needs a machine somewhere — to run a branch, run an agent, run a test suite, run a long-lived dev session. The usual options force a tradeoff: container sandboxes strip out half of the OS, microvm sandboxes cap at 8 vCPU and 24-hour sessions, raw cloud VMs take a half-hour of setup, and persistent VPSes leak state and bill you when idle.

Gibil is just the box. A fresh server with root, Docker, SSH, your repo cloned — forged in seconds, kept alive for as long as you set the TTL, gone when you're done. Today: a real Ubuntu Linux box on Hetzner Cloud at ~$0.008/hr (list price). On the roadmap: more clouds, more shapes — the CloudProvider interface is built for swap.

You're deep in a feature on main and Slack pings: "can you check why tests fail on feat/payments?" gibil branch feat/payments gives the branch its own box. Your local stays on main. Flow intact.

30-Second Demo

npm install -g gibil
gibil init                              # enter your Hetzner API token
gibil branch feat/payments --run "pnpm test"   # spins up a server, checks out the branch, runs tests
gibil ssh feat-payments                 # SSH in to debug
gibil destroy feat-payments             # gone, no trace

Install

npm install -g gibil

Forge. Run. Burn.

# Forge a server with your repo cloned and ready
gibil create --name my-app --repo github.com/you/project --ttl 30m

# Let your agent work on it
gibil run my-app "pnpm install && pnpm test"

# Or give any AI agent direct access via MCP
gibil mcp my-app

# Burn it when done
gibil destroy my-app

Why Gibil?

• A real machine, not a stripped sandbox — own kernel, full root, Docker-in-Docker, real systemd. Today's image is Ubuntu on Hetzner; the architecture targets any cloud, any shape.
• Don't switch branches — gibil branch feat/X gives the branch its own machine. Your local stays on main.
• Run your agent remotely — --agent claude installs Claude Code on the server. Also supports aider and codex. Direct filesystem access, no MCP latency.
• SSH when it breaks — gibil ssh <name> drops you into a real terminal. Debug live, not from CI logs.
• Preview a branch — --port 3000 tunnels the app to localhost. Open your browser, see the branch running live.
• Parallel branches — gibil branch feat/A feat/B feat/C boots three servers in parallel. Zero interference.
• MCP built in — gibil mcp gives any MCP-compatible agent direct access to a remote server.
• Ephemeral by default, persistent by choice — set a TTL from 15m to 30d, or extend it later. The box lives as long as the work does.
• BYOC — bring your own cloud. Your code stays in your account, not ours. Today: Hetzner. Multi-cloud on the roadmap.

Commands

Command	Description
gibil init	Set up gibil — Hetzner token, MCP config, agent skill
gibil create	Forge an ephemeral server
gibil branch <branch>	Spin up a branch on a clean server (auto-detects repo)
gibil checkout <branch>	Alias for gibil branch
gibil ssh <name>	SSH into a running server
gibil run <name> <cmd>	Execute a command remotely (--background for async)
gibil job <cmd>	Manage background jobs (status, list, cancel, logs)
gibil exec <name>	Upload and run a local script
gibil mcp [name]	Start MCP server for AI agents (--print-config for setup)
gibil list	List all active servers
gibil extend <name>	Extend a server's TTL
gibil destroy [name]	Burn down a server
gibil auth	Manage authentication
gibil usage	View usage and plan limits

Two Ways to Use Agents

Option A: Agent on your laptop (MCP)

Your agent runs locally and reaches into the server via MCP tools. Good for quick tasks where you want to watch the agent work. Works with any MCP-compatible agent.

gibil create --name my-app --repo github.com/you/project
gibil mcp     # Your agent gets vm_bash, vm_read, vm_write tools

Pros	Cons
See everything the agent does	Every file/command is a network round-trip
Agent uses your local config	Your laptop stays busy (fans, battery)
Works with any MCP-compatible agent	Long commands block with no streaming

Option B: Agent on the server (--agent)

The agent runs directly on the server. Your laptop is just a terminal. Good for heavy work, long sessions, or when you want your laptop free.

gibil branch feat/payments --agent claude
gibil ssh feat-payments

# Set your API key in the session (stays in memory, never written to disk)
export ANTHROPIC_API_KEY=sk-ant-...
claude    # direct filesystem access, full Docker, zero latency

# Also supports aider and codex:
gibil branch feat/payments --agent aider     # then: export ANTHROPIC_API_KEY=...
gibil branch feat/payments --agent codex     # then: export OPENAI_API_KEY=...

Pros	Cons
Direct filesystem — no MCP latency	Need to SSH in to interact
Full Docker, real Linux tools	Set API key manually after SSH
Your laptop is free	Need tmux to persist sessions
Works with claude, aider, codex

Security note: Don't pass API keys via --env — they end up on disk in /etc/environment. Instead, SSH in and export the key. It stays in memory and vanishes when the server is destroyed.

Rule of thumb: Quick checks → MCP (Option A). Heavy work or "let it run" → remote agent (Option B).

Preview a Branch

Run a dev server on a gibil server and open it in your browser:

gibil branch feat/payments --run "pnpm dev" --port 3000
# → Server created, branch checked out, dev server started
# → Local:  http://localhost:3000    ← open in your browser
# → Tunnel running in background

Or with an interactive SSH session and port forwarding:

gibil ssh feat-payments --port 3000 --port 8080
# → Forwarding localhost:3000 → feat-payments:3000
# → Forwarding localhost:8080 → feat-payments:8080
# → Tunnel active while SSH session is open

Both approaches tunnel traffic through SSH — encrypted, no public ports exposed, works behind any firewall.

Agent Workflow (JSON)

Every command supports --json for programmatic use:

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

Integrations

• Agent skill — works with Claude Code, Cursor, Copilot, Gemini CLI, and 40+ other agents:

  npx skills add https://github.com/AlexikM/gibil-skills --skill gibil
  

• VS Code extension — sidebar with live TTL countdowns, SSH terminal, run / extend / destroy actions. See vscode-extension/.
• Sandcastle provider — run Sandcastle agent loops on disposable gibil VMs instead of local Docker. See integrations/sandcastle/.

Links

• Documentation
• Quick Start
• Recipes
• Blog

License

Proprietary. See LICENSE for details.

_{Named after the Sumerian god of fire. The oldest flame, forging the newest servers.}