{"id":43209309,"url":"https://github.com/strahe/bwh","last_synced_at":"2026-02-01T07:14:25.186Z","repository":{"id":310602719,"uuid":"1040166768","full_name":"strahe/bwh","owner":"strahe","description":"Go SDK, CLI, and MCP server for managing BandwagonHost/bwg/搬瓦工 (KiwiVM) VPS, with command-line and programmatic access to most features.","archived":false,"fork":false,"pushed_at":"2026-01-30T12:54:47.000Z","size":103,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-31T04:05:18.496Z","etag":null,"topics":["bandwagonhost","bwg","bwh","cli","mcp-server"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strahe.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-18T14:55:49.000Z","updated_at":"2026-01-30T12:48:21.000Z","dependencies_parsed_at":"2025-08-19T06:26:15.702Z","dependency_job_id":"421e9dbc-e3e1-4166-973c-a7b23c27a878","html_url":"https://github.com/strahe/bwh","commit_stats":null,"previous_names":["strahe/bwh"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/strahe/bwh","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strahe%2Fbwh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strahe%2Fbwh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strahe%2Fbwh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strahe%2Fbwh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strahe","download_url":"https://codeload.github.com/strahe/bwh/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strahe%2Fbwh/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28971777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T06:46:42.625Z","status":"ssl_error","status_checked_at":"2026-02-01T06:44:56.173Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bandwagonhost","bwg","bwh","cli","mcp-server"],"created_at":"2026-02-01T07:14:24.543Z","updated_at":"2026-02-01T07:14:25.181Z","avatar_url":"https://github.com/strahe.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bwh\n\n[![CI](https://github.com/strahe/bwh/actions/workflows/ci.yml/badge.svg)](https://github.com/strahe/bwh/actions/workflows/ci.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/strahe/bwh)](https://goreportcard.com/report/github.com/strahe/bwh)\n[![Release](https://img.shields.io/github/v/release/strahe/bwh)](https://github.com/strahe/bwh/releases)\n\n\u003e **English | [中文](README.zh.md)**\n\n## Overview\n\nGo SDK, CLI, and MCP server for managing BandwagonHost (KiwiVM) VPS, with command-line and programmatic access to most features.\n\n## Installation\n\nPrerequisites: Go 1.24+; KiwiVM VEID and API key.\n\n```bash\n# CLI or MCP\ngo install github.com/strahe/bwh/cmd/bwh@latest\n\n# Go SDK\ngo get github.com/strahe/bwh\n```\n\n## Quick Start\n\n```bash\n# Configure your VPS\nbwh node add production --api-key \u003cAPI_KEY\u003e --veid \u003cVEID\u003e\n\n# Basic operations\nbwh info                              # View server details\nbwh start/stop/restart                # Power management\nbwh usage --period 7d                 # Check usage statistics\nbwh snapshot create \"backup-name\"     # Create snapshots\nbwh iso images                        # List available ISO images\nbwh iso mount ubuntu-20.04.iso        # Mount ISO for rescue/install\nbwh ipv6 add                          # Assign new IPv6 /64 subnet\nbwh ipv6 list                         # List IPv6 subnets\nbwh pi info                           # Show private IPv4 info (alias of `private-ip info`)\nbwh connect                           # SSH connection\n\n# Keep BWH CLI up to date\nbwh update                            # Check and install updates\nbwh update --check                    # Only check for updates\n\n# Explore more commands: bwh --help\n```\n\n### Multi-Instance Support\n\n```bash\n# Add multiple VPS instances\nbwh node add prod --api-key \u003cKEY\u003e --veid \u003cVEID\u003e\nbwh node add dev --api-key \u003cKEY\u003e --veid \u003cVEID\u003e\n\n# Target specific instance or set default\nbwh --instance prod info\nbwh node set-default prod\n\n# View all options: bwh node --help\n```\n\n## Go SDK\n\n```go\nimport (\n    \"context\"\n    \"log\"\n    \"github.com/strahe/bwh/pkg/client\"\n)\n\n// Initialize client\nc := client.NewClient(\"your-api-key\", \"your-veid\")\nctx := context.Background()\n\n// Get server information\ninfo, err := c.GetServiceInfo(ctx)\nif err != nil {\n    log.Fatal(err)\n}\n\n// Power management\nerr = c.Start(ctx)                    // Start VPS\nerr = c.Stop(ctx)                     // Stop VPS\nerr = c.Restart(ctx)                  // Restart VPS\n\n// Monitoring\nusage, err := c.GetRawUsageStats(ctx) // Usage statistics\nlive, err := c.GetLiveServiceInfo(ctx) // Real-time status\n\n// Backup management\nsnapshot, err := c.CreateSnapshot(ctx, \"backup-name\")\nbackups, err := c.ListBackups(ctx)\n```\n\n### Available Methods\n\n**Server Management**: `GetServiceInfo`, `GetLiveServiceInfo`, `Start`, `Stop`, `Restart`, `Kill`, `SetHostname`, `ReinstallOS`, `ResetRootPassword`, `MountISO`, `UnmountISO`\n\n**Monitoring**: `GetRawUsageStats`, `GetBasicServiceInfo`, audit log access\n\n**Backup \u0026 Recovery**: `CreateSnapshot`, `RestoreSnapshot`, `DeleteSnapshot`, backup management\n\n**Migration**: `GetMigrateLocations`, `StartMigration` (use `StartMigrationWithTimeout` for custom timeouts)\n\n**Network**: SSH key management, IP/reverse DNS configuration, IPv6 subnet management, private IPv4 management\n\n*Complete API reference*: View [pkg/client documentation](./pkg/client) or run `go doc github.com/strahe/bwh/pkg/client` for all available methods.\n\n## MCP Server Integration\n\nBWH includes a built-in MCP (Model Context Protocol) server that enables secure AI integration with your VPS management workflows.\n\n### Start MCP Server\n\n```bash\nbwh mcp serve\n```\n\n### Configuration\n\nThe BWH MCP server integrates seamlessly with various AI tools and editors. Add the appropriate configuration to your MCP client:\n\n#### Claude Desktop\n\nAdd to your `claude_desktop_config.json` file:\n\n```json\n{\n  \"mcpServers\": {\n    \"bwh\": {\n      \"command\": \"bwh\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n\n\n#### Claude Code\n\n```bash\nclaude mcp add bwh -- bwh mcp serve\n```\n\n\n\n#### Cursor\n\nAdd to your Cursor MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"bwh\": {\n      \"command\": \"bwh\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n```\n\n\n\n#### Continue (VS Code Extension)\n\nAdd to your Continue configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"bwh\": {\n      \"transport\": {\n        \"type\": \"stdio\",\n        \"command\": \"bwh\",\n        \"args\": [\"mcp\", \"serve\"]\n      }\n    }\n  }\n}\n```\n\n\n\n### Configuration Notes\n\n- **Custom Config**: Use `--config /path/to/config.yaml` to specify a config file\n- **Multiple Instances**: The server automatically uses your default instance from configuration\n- **Integration**: Add to existing MCP config files without replacing other servers\n\n### Available MCP Tools (Read-only)\n\n- **instance_list**: List all configured instances with metadata (no parameters)\n- **vps_info_get**: Get VPS information (`instance?`, `compact?`, `live?`)\n- **vps_usage_get**: Get usage statistics (`instance?`, `period?`, `days?`, `group_by?`)\n- **snapshot_list**: List snapshots (`instance?`, `sticky_only?`, `name_contains?`, `sort_by?`, `order?`, `limit?`)\n- **backup_list**: List backups (`instance?`, `os_contains?`, `since?`, `until?`, `sort_by?`, `order?`, `limit?`)\n- **vps_audit_get**: Get audit logs (`instance?`, `since?`, `until?`, `limit?`, `ip_contains?`, `type?`)\n- **iso_list**: List available and mounted ISO images (`instance?`)\n\nAll MCP tools are safe, read-only operations that won't modify your VPS configuration or data.\n\n## Shell Completion\n\n```bash\nbwh completion bash \u003e /usr/local/share/bash-completion/completions/bwh  # bash (Linux)\nbwh completion bash \u003e /opt/homebrew/etc/bash_completion.d/bwh           # bash (macOS)\nbwh completion zsh \u003e /usr/local/share/zsh/site-functions/_bwh           # zsh (system)\nbwh completion fish \u003e ~/.config/fish/completions/bwh.fish              # fish (user)\n```\n\n## Available Commands\n\n```\nnode            Manage BWH VPS nodes configuration\ninfo            Display comprehensive VPS information\nrate-limit      Check API rate limit status\nconnect         SSH into VPS (passwordless, using local SSH keys)\nssh             Manage SSH keys\nstart/stop      Start/stop the VPS\nrestart         Restart the VPS\nkill            Forcefully stop a stuck VPS (WARNING: potential data loss)\nhostname        Set hostname for the VPS\nset-ptr         Set PTR (rDNS) record for IP address\niso             Manage ISO images for VPS boot\nreinstall       Reinstall VPS operating system (WARNING: destroys all data)\nusage           Display detailed VPS usage statistics\naudit           Display audit log entries\nreset-password  Reset the root password\nsnapshot        Manage VPS snapshots\nbackup          Manage VPS backups\nmigrate         Migrate VPS to another location (supports --wait/--timeout)\nipv6            Manage IPv6 subnets (add, delete, list)\nprivate-ip (pi) Manage Private IPv4 addresses (info, available, assign, delete)\nmcp             Run MCP server for read-only BWH management\nupdate          Check for updates and update BWH CLI to the latest version\ncompletion      Generate shell completion script\n```\n\nUse `bwh \u003ccommand\u003e --help` to view detailed options and usage examples for each command.\n\n## Build\n\n```bash\nmake build  # or: go build -o bwh ./cmd/bwh\n```\n\nRun tests: `make test`\n\n## License\n\nMIT. See `LICENSE`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrahe%2Fbwh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrahe%2Fbwh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrahe%2Fbwh/lists"}