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

1. Create a Vultr account

1. Go to my.vultr.com
2. Sign up / log in
3. Add a payment method (Vultr requires this before issuing API keys)

2. Generate an API key

1. Go to my.vultr.com/settings/#settingsapi
2. Click Enable API
3. Copy your Personal Access Token
4. Optional but recommended: scope the API to a subnet under Access Control if you only call it from a known IP

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