Provider Setup

Gibil works with Hetzner Cloud (cheap EU/US, ARM SKUs) and Vultr (APAC density: Tokyo, Seoul, Singapore, Sydney, Mumbai, plus the rest of the world). Pick one to start; you can add the second any time with gibil init --add.

Option A: Hetzner Cloud

1. Create a Hetzner Cloud account

1. Go to console.hetzner.cloud
2. Sign up / log in
3. Create a new project (e.g. "my-gibil-project")

2. Generate an API token

1. In your project, go to Security → API Tokens
2. Click Generate API Token
3. Name: gibil-dev
4. Permissions: Read & Write
5. Copy the token (you won't see it again)

3. Run the setup wizard

gibil init

Pick Hetzner when prompted, paste the token. The wizard validates it and saves it under providers.hetzner in ~/.gibil/config.json.

  ✓ Hetzner token verified
  🦎 The forge is ready. Run gibil create to light your first fire.

Non-interactive: gibil init --provider hetzner --token $HETZNER_API_TOKEN.

Option B: Vultr

New Vultr customers can sign up via this link for $300 in free credits, enough for weeks of Gibil usage on small VMs. _{Referral link. Gibil gets a kickback that helps fund development.}

For the full hand-holding walkthrough (with the IP whitelist gotcha called out), see Vultr Setup. The short version:

1. Create a Vultr account

1. Sign up at Vultr
2. Add a payment method (Vultr requires this before issuing API keys)

2. Generate an API key

1. Go to console.vultr.com/user/apiaccess
2. Important: under Access Control, add your current IP (or 0.0.0.0/0 for personal use). Vultr blocks API requests until you do this
3. Copy your Personal Access Token from the top of the page

3. Run the setup wizard

gibil init

Pick Vultr when prompted, paste the token. The wizard validates it against the Vultr API and saves it under providers.vultr in ~/.gibil/config.json. Default region is nrt (Tokyo).

Non-interactive: gibil init --provider vultr --token $VULTR_API_KEY.

Add a second provider later

Already have one set up? Add the other:

gibil init --add vultr      # if you started with Hetzner
gibil init --add hetzner    # if you started with Vultr

See what's available

Before forging anything:

gibil providers

Lists every configured provider, the default region, and the size catalog (small / medium / large) with concrete vCPU / RAM / disk specs. No token needed; the catalog is static metadata. gibil providers --json for agents.

Test the full pipeline

# Step 1: Forge a server (uses your default provider)
gibil create --name test-1 --ttl 15

# Or pick a specific provider and region:
gibil create --name tokyo-test --provider vultr --location nrt --size small --ttl 15

# Step 2: List it (the PROVIDER column shows which cloud)
gibil list

# Step 3: SSH into it
gibil ssh test-1
# Run: node --version   (should show v20.x)
# Run: exit

# Step 4: Run a remote command
gibil run test-1 "uname -a && node --version"

# Step 5: Run with JSON output
gibil run test-1 "echo hello from gibil" --json

# Step 6: Extend TTL
gibil extend test-1 30m

# Step 7: Burn it down
gibil destroy test-1

Test with a repo

# Forge with a repo (auto-clones on boot)
gibil create --name repo-test \
  --repo https://github.com/vercel/next.js \
  --ttl 15

# Verify repo was cloned
gibil run repo-test "ls /root/project"

# Clean up
gibil destroy repo-test

Test fleet mode

# Forge 3 servers in parallel
gibil create --name fleet --fleet 3 --ttl 10 --json

# List all
gibil list

# Burn them all
gibil destroy --all

Cleanup checklist

After testing, make sure everything is cleaned up:

• Run gibil destroy --all to burn any remaining servers
• Check Hetzner Console → Servers for any orphaned gibil-* servers and SSH keys
• Check Vultr Console → Products → Cloud Compute and Account → API → SSH Keys for any orphaned gibil-* resources