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.yamlto specify a config file - Multiple Instances: The server uses the configured default instance, or
--instance <name>as the MCP session default. Tool-levelinstancearguments 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.
No comments yet
Be the first to share your take.