How to Set Up the CubeSandbox Environment: Complete Development VM Guide

CubeSandbox provides a disposable OpenCloudOS 9 VM with helper scripts that download a cloud image, forward development ports, and install core services automatically.

TencentCloud/CubeSandbox offers an isolated development environment that protects your host system while you build and test the platform. The setup process uses automation scripts in the dev-env/ directory to prepare a QEMU/KVM virtual machine, initialize the guest OS, and deploy the Cube Sandbox stack. This guide walks through how to set up the CubeSandbox environment using the official helper scripts and verified code paths.

Step 1: Prepare the VM Image

The dev-env/prepare_image.sh script handles the initial VM image creation. It downloads an OpenCloudOS 9 cloud image, expands it to 100 GB, and performs in-guest initialization including root filesystem growth, SELinux tweaks, PATH fixes, and login banner configuration.

According to the source code in /dev-env/README.md#L48-L58, the script also creates a systemd autostart unit to ensure Cube components launch automatically after reboots.

Run the preparation once:

./prepare_image.sh

Step 2: Boot the Development VM

Start the virtual machine using dev-env/run_vm.sh, which launches QEMU with KVM acceleration and forwards essential ports to your host. As documented in /dev-env/README.md#L12-L18, the forwarded ports include:

• 10022 for SSH access
• 13000 for Cube API
• 11080 for Cube HTTP
• 11443 for Cube TLS
• 12088 for WebUI

Keep this terminal open while working:

./run_vm.sh

Step 3: Install Cube Sandbox Inside the VM

Open a second terminal and connect to the running VM using dev-env/login.sh. This thin wrapper opens an SSH session to the guest on port 10022, optionally as root, as implemented in /dev-env/README.md#L73-L78.

Inside the VM, install Cube Sandbox using the one-click deployment script:

curl -sL https://github.com/tencentcloud/CubeSandbox/raw/master/deploy/one-click/online-install.sh | bash

This command fetches the latest release and starts the core services: network-agent, cubemaster, cube-api, and cubelet (see /dev-env/README.md#L84-L92).

Step 4: Verify the Installation

Confirm the platform is healthy by checking the API endpoint:

curl -sf http://127.0.0.1:3000/health && echo OK

A successful response indicates that all Cube Sandbox components are running correctly inside the VM.

Enable Automatic Startup After Reboot

To persist across VM reboots, enable the systemd autostart unit. The dev-env/cube-autostart.sh script manages the cube-sandbox-oneclick.service unit, which automatically launches all Cube components on boot as described in /dev-env/README.md#L101-L112.

From the host, run:

./cube-autostart.sh      # defaults to "enable"

./cube-autostart.sh status

Development Workflow: Build and Sync

Iterate on code changes without rebuilding the VM. Edit source code locally, rebuild binaries, and copy them into the running VM using dev-env/sync_to_vm.sh. This script only copies files and does not rebuild or restart services, giving you full control over the update workflow (see /dev-env/README.md#L23-L33 and /dev-env/README.md#L84-L90).

Rebuild locally:

make all

Sync specific binaries:

./sync_to_vm.sh bin cubemaster cubelet

Then restart services inside the VM (via the login.sh session):

systemctl restart cube-sandbox-oneclick.service

Debugging and Log Collection

When troubleshooting, use dev-env/copy_logs.sh to archive logs from the guest. This script collects /data/log from the VM and produces a data-log-<timestamp>.tar.gz archive next to the dev-env/ directory for host-side analysis.

./copy_logs.sh

Summary

• Prepare the image once with prepare_image.sh to download and configure the OpenCloudOS 9 VM.
• Boot the VM with run_vm.sh, which forwards ports 10022, 13000, 11080, 11443, and 12088 to the host.
• Install Cube Sandbox inside the VM using the online one-click script, then verify with curl http://127.0.0.1:3000/health.
• Enable persistence using cube-autostart.sh to configure the systemd unit for automatic startup.
• Iterate efficiently by rebuilding locally and using sync_to_vm.sh to update binaries without VM recreation.

Frequently Asked Questions

What ports does the CubeSandbox VM forward to the host?

The run_vm.sh script forwards five essential ports: SSH on 10022, Cube API on 13000, Cube HTTP on 11080, Cube TLS on 11443, and WebUI on 12088. This allows you to access services from your host browser and SSH client while the VM runs in isolation.

How do I persist Cube Sandbox services across VM reboots?

Run ./cube-autostart.sh from the host to enable the cube-sandbox-oneclick.service systemd unit inside the VM. This unit, as configured in /dev-env/README.md#L101-L112, automatically starts network-agent, cubemaster, cube-api, and cubelet on every boot, eliminating the need to reinstall after shutdown.

Can I update code without destroying the VM?

Yes. Use the iterative development workflow: rebuild binaries locally with make all, then run ./sync_to_vm.sh bin <component> to copy updates into the running VM. This script only transfers files; you manually restart services with systemctl restart cube-sandbox-oneclick.service to apply changes, giving you precise control over the update process.

What operating system runs inside the development VM?

The CubeSandbox environment uses OpenCloudOS 9 as its base image. The prepare_image.sh script downloads the official cloud image, expands it to 100 GB, and applies SELinux tweaks and PATH fixes to create a standardized development environment according to /dev-env/README.md#L48-L58.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}