How to Configure CubeSandbox: Complete Development Environment Setup

CubeSandbox provides a disposable OpenCloudOS 9 VM with automated helper scripts that download cloud images, configure port forwarding, and install core services via a one-click installer.

CubeSandbox is TencentCloud's containerized sandbox platform for building and testing cloud-native workloads. The repository includes a complete development environment in the dev-env/ directory that uses QEMU/KVM virtualization to isolate the platform from your host system while maintaining fast iteration cycles.

Prepare the VM Image with OpenCloudOS 9

The first step to configure CubeSandbox is preparing the base virtual machine image. The dev-env/prepare_image.sh script automates this process by downloading an OpenCloudOS 9 cloud image, expanding it to 100 GB, and performing in-guest initialization.

According to the source code at /dev-env/README.md#L48-L58, this initialization includes:

• Growing the root filesystem to utilize the full disk
• Applying SELinux security tweaks
• Fixing PATH environment variables
• Setting up the login banner
• Creating systemd autostart units

Run the preparation script once before your first boot:

./prepare_image.sh

Boot and Access the Development VM

Starting the VM with KVM Acceleration

The dev-env/run_vm.sh script launches the VM with hardware acceleration and configures the network stack. As documented in /dev-env/README.md#L12-L18, it forwards critical ports to your host:

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

Start the VM and keep the terminal open:

./run_vm.sh

Connecting via SSH

Use dev-env/login.sh to open a secure shell session. The script handles the connection details, defaulting to the root user but supporting alternative usernames via command-line arguments.

From a second terminal, run:

./login.sh

Install CubeSandbox Inside the VM

Once logged into the guest, install the platform using the one-click installer. As specified in /dev-env/README.md#L84-L92, this downloads the latest release and starts the core services: network-agent, cubemaster, cube-api, and cubelet.

Execute the installation:

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

Verify the Installation

Confirm the platform is operational by checking the health endpoint on port 3000:

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

A successful response indicates all CubeSandbox services are running correctly.

Configure Persistence with Systemd Autostart

To ensure CubeSandbox services survive 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 components on boot.

From the host (after verifying the installation), run:

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

Check the service status at any time:

./cube-autostart.sh status

This configuration persists across reboots according to /dev-env/README.md#L101-L112.

Development Workflow: Syncing Code Changes

The CubeSandbox development environment supports iterative development on your host machine. Edit source code locally, rebuild binaries, and copy them into the running VM without rebuilding the entire environment.

The dev-env/sync_to_vm.sh script (documented in /dev-env/README.md#L23-L33) copies files only—it does not rebuild or restart services, giving you full control over the update workflow.

Typical iteration cycle:

# Rebuild locally

make all

# Copy updated binaries into the VM

./sync_to_vm.sh bin cubemaster cubelet

# Restart services inside the VM (run in the login.sh session)

systemctl restart cube-sandbox-oneclick.service

Collect Logs for Debugging

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

./copy_logs.sh

Summary

• VM Preparation: Use prepare_image.sh to download and configure an OpenCloudOS 9 image with 100 GB storage and SELinux tweaks.
• Network Access: run_vm.sh forwards ports 10022 (SSH), 13000 (API), 11080 (HTTP), 11443 (TLS), and 12088 (WebUI) to the host.
• Installation: Execute the online installer inside the VM to deploy network-agent, cubemaster, cube-api, and cubelet.
• Persistence: Enable cube-sandbox-oneclick.service via cube-autostart.sh to maintain services across reboots.
• Development: Use sync_to_vm.sh to copy rebuilt binaries from host to guest without destroying the VM state.

Frequently Asked Questions

What operating system does the CubeSandbox development VM use?

The development environment uses an OpenCloudOS 9 cloud image. The prepare_image.sh script downloads this image automatically and expands it to 100 GB, applying necessary SELinux configurations and PATH fixes during initialization.

Which ports are forwarded to the host when running the CubeSandbox VM?

The run_vm.sh script configures QEMU to forward 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 the VM and CubeSandbox services using localhost addresses from your host machine.

How do I persist CubeSandbox services across VM reboots?

Run ./cube-autostart.sh from the host after the initial installation. This enables the cube-sandbox-oneclick.service systemd unit inside the VM, which automatically starts network-agent, cubemaster, cube-api, and cubelet on system boot.

Can I develop CubeSandbox code on my host machine and test it in the VM?

Yes. The sync_to_vm.sh script copies rebuilt binaries from your host to the running VM without requiring a full rebuild or VM restart. After syncing, manually restart the services using systemctl restart cube-sandbox-oneclick.service inside the VM to apply your changes.

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