bwh

English | 中文

Overview

Go SDK, CLI, and MCP server for managing BandwagonHost (KiwiVM) VPS, with command-line and programmatic access to most features.

Installation

Prerequisites: Go 1.24+; KiwiVM VEID and API key.

# CLI or MCP
go install github.com/strahe/bwh/cmd/bwh@latest

# Go SDK
go get github.com/strahe/bwh/pkg/client@latest

Quick Start

# Configure your VPS
bwh node add production --api-key <API_KEY> --veid <VEID>

# Basic operations
bwh info                              # View server details
bwh rate-limit                        # Check API rate limit status
bwh start/stop/restart                # Power management
bwh usage --period 7d                 # Check usage statistics
bwh abuse suspensions                 # Show suspension details
bwh notifications list                # Show notification preferences
bwh notifications set <id> on --dry-run # Preview notification changes
bwh snapshot create "backup-name"     # Create snapshots
bwh iso images                        # List available ISO images
bwh iso mount ubuntu-20.04.iso        # Mount ISO for rescue/install
bwh ipv6 add                          # Assign new IPv6 /64 subnet
bwh ipv6 list                         # List IPv6 subnets
bwh pi info                           # Show private IPv4 info (alias of `private-ip info`)
bwh connect                           # SSH connection

# Keep BWH CLI up to date
bwh update                            # Check and install updates
bwh update --check                    # Only check for updates

# Explore more commands: bwh --help

Multi-Instance Support

# Add multiple VPS instances
bwh node add prod --api-key <KEY> --veid <VEID>
bwh node add dev --api-key <KEY> --veid <VEID>

# Target specific instance or set default
bwh --instance prod info
bwh node set-default prod

# View all options: bwh node --help

Go SDK

import (
    "context"
    "log"
    "github.com/strahe/bwh/pkg/client"
)

// Initialize client
c := client.NewClient("your-api-key", "your-veid")
ctx := context.Background()

// Get server information
info, err := c.GetServiceInfo(ctx)
if err != nil {
    log.Fatal(err)
}

// Power management
err = c.Start(ctx)                    // Start VPS
err = c.Stop(ctx)                     // Stop VPS
err = c.Restart(ctx)                  // Restart VPS

// Monitoring
usage, err := c.GetRawUsageStats(ctx) // Usage statistics
live, err := c.GetLiveServiceInfo(ctx) // Real-time status

// Backup management
snapshot, err := c.CreateSnapshot(ctx, "backup-name")
backups, err := c.ListBackups(ctx)

Available Methods

The SDK sends read-only API calls with GET query parameters and state-changing API calls with POST application/x-www-form-urlencoded form data. For write calls, request parameters and credentials are not placed in the URL.

Server Management: GetServiceInfo, GetLiveServiceInfo, Start, Stop, Restart, Kill, SetHostname, ReinstallOS, ResetRootPassword, MountISO, UnmountISO

Monitoring: GetRawUsageStats, GetAuditLog, GetRateLimitStatus

Backup & Recovery: CreateSnapshot, RestoreSnapshot, DeleteSnapshot, backup management

Migration: GetMigrateLocations, StartMigration (use StartMigrationWithTimeout for custom timeouts)

Security & Abuse: GetSuspensionDetails, GetPolicyViolations, Unsuspend, ResolvePolicyViolation

Notifications: GetNotificationPreferences, SetNotificationPreferences

Network: SSH key management, IP/reverse DNS configuration, IPv6 subnet management, private IPv4 management

Complete API reference: View the pkg.go.dev package documentation or run go doc github.com/strahe/bwh/pkg/client for all available methods.

MCP Server Integration

BWH includes a built-in MCP (Model Context Protocol) server that enables secure AI integration with your VPS management workflows.

Start MCP Server

bwh mcp serve

Configuration

The BWH MCP server integrates seamlessly with various AI tools and editors. Add the appropriate configuration to your MCP client:

Claude Desktop

Add to your claude_desktop_config.json file:

{
  "mcpServers": {
    "bwh": {
      "command": "bwh",
      "args": ["mcp", "serve"]
    }
  }
}

Claude Code

claude mcp add bwh -- bwh mcp serve

Cursor

Add to your Cursor MCP configuration:

{
  "mcpServers": {
    "bwh": {
      "command": "bwh",
      "args": ["mcp", "serve"]
    }
  }
}

Continue (VS Code Extension)

Add to your Continue configuration:

{
  "mcpServers": {
    "bwh": {
      "transport": {
        "type": "stdio",
        "command": "bwh",
        "args": ["mcp", "serve"]
      }
    }
  }
}

Configuration Notes

• Custom Config: Use --config /path/to/config.yaml to specify a config file
• Multiple Instances: The server uses the configured default instance, or --instance <name> as the MCP session default. Tool-level instance arguments override it.
• Integration: Add to existing MCP config files without replacing other servers

Available MCP Tools (Read-only)

• instance_list: List all configured instances with metadata (no parameters)
• vps_info_get: Get VPS information (instance?, compact?, live?)
• vps_usage_get: Get usage statistics (instance?, period?, days?, group_by?)
• snapshot_list: List snapshots (instance?, sticky_only?, name_contains?, sort_by?, order?, limit?)
• backup_list: List backups (instance?, os_contains?, since?, until?, sort_by?, order?, limit?)
• vps_audit_get: Get audit logs (instance?, since?, until?, limit?, ip_contains?, type?)
• iso_list: List available and mounted ISO images (instance?)
• ssh_keys_get: Get SSH public keys (instance?, full?)
• os_templates_get: List OS templates (instance?)
• rate_limit_get: Get API rate limit status (instance?)
• migration_locations_get: List migration locations (instance?)
• private_ip_available_get: List available private IPv4 addresses (instance?)
• abuse_suspensions_get: Get suspension details (instance?)
• abuse_policy_get: Get policy violations (instance?)
• notification_preferences_get: Get notification preferences (instance?)

All MCP tools are safe, read-only operations that won't modify your VPS configuration or data.

Shell Completion

bwh completion bash > /usr/local/share/bash-completion/completions/bwh  # bash (Linux)
bwh completion bash > /opt/homebrew/etc/bash_completion.d/bwh           # bash (macOS)
bwh completion zsh > /usr/local/share/zsh/site-functions/_bwh           # zsh (system)
bwh completion fish > ~/.config/fish/completions/bwh.fish              # fish (user)

Available Commands

node            Manage BWH VPS nodes configuration
info            Display comprehensive VPS information
rate-limit      Check API rate limit status
connect         SSH into VPS (passwordless, using local SSH keys)
ssh             Manage SSH keys
start/stop      Start/stop the VPS
restart         Restart the VPS
kill            Forcefully stop a stuck VPS (WARNING: potential data loss)
hostname        Set hostname for the VPS
set-ptr         Set PTR (rDNS) record for IP address
iso             Manage ISO images for VPS boot
reinstall       Reinstall VPS operating system (WARNING: destroys all data)
usage           Display detailed VPS usage statistics
audit           Display audit log entries
abuse           Display and resolve suspension details and policy violations
notifications   Display and update KiwiVM notification preferences
reset-password  Reset the root password
snapshot        Manage VPS snapshots
backup          Manage VPS backups
migrate         Migrate VPS to another location (supports --wait/--timeout)
ipv6            Manage IPv6 subnets (add, delete, list)
private-ip (pi) Manage Private IPv4 addresses (info, available, assign, delete)
mcp             Run MCP server for read-only BWH management
update          Check for updates and update BWH CLI to the latest version
completion      Generate shell completion script

Use bwh <command> --help to view detailed options and usage examples for each command.

Write API Safety

bwh reinstall --os debian-12-x86_64 --dry-run
bwh reset-password --dry-run
bwh ssh set "ssh-ed25519 AAAA..." --dry-run
bwh migrate start us-west --dry-run
bwh abuse unsuspend <record_id> --dry-run
bwh notifications set <preference_id> <on|off> --dry-run

Most commands that call KiwiVM write APIs support --dry-run to validate and preview without calling the write API. Add --yes only when you want to skip the y/N prompt. Existing --force flags on dangerous commands such as kill and reinstall remain supported for compatibility.

Build

make build  # or: go build -o bwh ./cmd/bwh

Run tests: make test

License

MIT. See LICENSE.