# How to Configure CubeSandbox: Complete Development Environment Setup

> Configure CubeSandbox for a quick development environment setup. This guide helps you set up a disposable OpenCloudOS 9 VM with automated scripts for cloud images, port forwarding, and core services.

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

---

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

```bash
./prepare_image.sh

```

## Boot and Access the Development VM

### Starting the VM with KVM Acceleration

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

```bash
./run_vm.sh

```

### Connecting via SSH

Use [`dev-env/login.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

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

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

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

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

```

Check the service status at any time:

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

```bash

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

```bash
./copy_logs.sh

```

## Summary

- **VM Preparation**: Use [`prepare_image.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/prepare_image.sh) to download and configure an OpenCloudOS 9 image with 100 GB storage and SELinux tweaks.
- **Network Access**: [`run_vm.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/cube-autostart.sh) to maintain services across reboots.
- **Development**: Use [`sync_to_vm.sh`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/./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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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.