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

> Easily set up your CubeSandbox development environment. Get a disposable OpenCloudOS 9 VM with automated setup for cloud images, ports, and services. Start coding faster today!

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: getting-started
- Published: 2026-07-14

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
./prepare_image.sh

```

## Step 2: Boot the Development VM

Start the virtual machine using [`dev-env/run_vm.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
./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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
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:

```bash
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
./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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

```bash
make all

```

Sync specific binaries:

```bash
./sync_to_vm.sh bin cubemaster cubelet

```

Then restart services inside the VM (via the [`login.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/login.sh) session):

```bash
systemctl restart cube-sandbox-oneclick.service

```

## Debugging and Log Collection

When troubleshooting, use [`dev-env/copy_logs.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.

```bash
./copy_logs.sh

```

## Summary

- **Prepare the image** once with [`prepare_image.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/prepare_image.sh) to download and configure the OpenCloudOS 9 VM.
- **Boot the VM** with [`run_vm.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-autostart.sh) to configure the systemd unit for automatic startup.
- **Iterate efficiently** by rebuilding locally and using [`sync_to_vm.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/./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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`.