# How to Backup CubeSandbox Configuration: Complete Guide for TencentCloud/CubeSandbox

> Learn how to backup CubeSandbox configuration on TencentCloud. Follow this guide to copy YAML files, preserve .env, export MySQL, and snapshot Redis for complete data protection.

- Repository: [Tencent Cloud/CubeSandbox](https://github.com/TencentCloud/CubeSandbox)
- Tags: how-to-guide
- Published: 2026-07-13

---

**To backup CubeSandbox configuration, copy the three YAML config files from `configs/single-node/`, preserve the `.env` file, export the MySQL databases (`ossdb_config` and `instance_db_config`) using `mysqldump`, and optionally snapshot Redis with `redis-cli --rdb`.**

CubeSandbox is an open-source sandbox environment maintained by TencentCloud that stores its operational settings across YAML files, environment variables, and persistent data stores. A complete backup strategy must capture static service parameters, runtime overrides, and database state to ensure a full recovery. Below is the authoritative breakdown of where configuration lives and how to archive it correctly.

## Where CubeSandbox Stores Configuration

Understanding the three-tier storage architecture is essential before executing any backup commands.

### Static YAML Configuration Files

The core service parameters reside in `configs/single-node/` within the repository. These files define ports, timeouts, feature flags, and database connections.

- **[`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml)**: Master node settings including HTTP port, Cubelet gRPC endpoints, authentication, and connections to `ossdb_config` and `instance_db_config`.
- **[`configs/single-node/cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubelet.yaml)**: Worker-node defaults for resource limits, isolation flags, and sandbox idle TTL.
- **[`configs/single-node/network-agent.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/network-agent.yaml)**: Network-policy parameters and egress control rules.

### Environment Variable Overrides (.env)

Runtime overrides and secrets are managed via a hidden `.env` file (or the equivalent Docker Compose environment block). This file typically contains:

- `WEB_UI_ENABLE` and `WEB_UI_HOST_PORT` toggles
- `CUBE_SANDBOX_MYSQL_USER` and `CUBE_SANDBOX_MYSQL_PASSWORD` credentials
- External service endpoints

### MySQL Databases (Runtime State)

According to the [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml) source, CubeSandbox references two logical MySQL databases:

- **`ossdb_config`**: Stores template snapshots, sandbox metadata, and credential vault data.
- **`instance_db_config`**: Holds per-instance runtime state and resource allocation tables.

### Redis Cache (Optional)

Redis maintains node-metric keys and sandbox-proxy routing information. While the system can rebuild metric data on restart, capturing a point-in-time RDB snapshot ensures complete state preservation.

## Step-by-Step Backup Procedure

Execute these steps on the host running CubeSandbox to create a portable archive.

### Step 1: Archive the YAML Files

Create a backup directory and copy the static configurations:

```bash
mkdir -p /backup/cubesandbox/config

cp configs/single-node/cubemaster.yaml /backup/cubesandbox/config/
cp configs/single-node/cubelet.yaml /backup/cubesandbox/config/
cp configs/single-node/network-agent.yaml /backup/cubesandbox/config/

```

### Step 2: Preserve Environment Variables

If you maintain a custom `.env` file, secure it alongside the YAMLs:

```bash
if [ -f .env ]; then
    cp .env /backup/cubesandbox/config/
fi

```

**Security note:** Never commit backups containing passwords to version control. Store the `.env` backup in a secure location.

### Step 3: Export MySQL Databases

Extract credentials from [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml) or your `.env` file, then dump both databases:

```bash

# Set variables (replace with actual values from your config)

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=cube
MYSQL_PASS=your_secure_password

mkdir -p /backup/cubesandbox/mysql

# Export ossdb_config

mysqldump -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p"$MYSQL_PASS" \
    ossdb_config > /backup/cubesandbox/mysql/ossdb.sql

# Export instance_db_config

mysqldump -h $MYSQL_HOST -P $MYSQL_PORT -u $MYSQL_USER -p"$MYSQL_PASS" \
    instance_db_config > /backup/cubesandbox/mysql/instance.sql

```

### Step 4: Snapshot Redis (Optional)

Capture the Redis RDB dump using the port specified in [`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml) (default is typically 6379):

```bash
mkdir -p /backup/cubesandbox/redis

redis-cli -h 127.0.0.1 -p 6379 --rdb /backup/cubesandbox/redis/dump.rdb

```

### Step 5: Compress the Backup Archive

Bundle all components into a single compressed file:

```bash
tar -czvf cubesandbox-backup-$(date +%F).tar.gz \
    -C /backup/cubesandbox \
    config mysql redis

```

## Automated Backup Script

For production environments, automate the workflow with this bash script that parses credentials directly from [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml):

```bash
#!/usr/bin/env bash
set -euo pipefail

BACKUP_ROOT=/backup/cubesandbox
mkdir -p "$BACKUP_ROOT"/{config,mysql,redis}

# 1. Copy YAML configs

cp configs/single-node/*.yaml "$BACKUP_ROOT/config/"

# 2. Copy .env if present

[[ -f .env ]] && cp .env "$BACKUP_ROOT/config/"

# 3. Extract MySQL credentials from cubemaster.yaml and dump databases

MYSQL_USER=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'user' | head -1 | cut -d':' -f2 | tr -d ' "')
MYSQL_PASS=$(grep -A1 'ossdb_config' configs/single-node/cubemaster.yaml | grep 'pwd' | head -1 | cut -d':' -f2 | tr -d ' "')

mysqldump -u"$MYSQL_USER" -p"$MYSQL_PASS" ossdb_config > "$BACKUP_ROOT/mysql/ossdb.sql"
mysqldump -u"$MYSQL_USER" -p"$MYSQL_PASS" instance_db_config > "$BACKUP_ROOT/mysql/instance.sql"

# 4. Snapshot Redis (optional)

REDIS_PORT=$(grep -A1 'redis:' configs/single-node/cubemaster.yaml | grep 'port' | head -1 | cut -d':' -f2 | tr -d ' "')
redis-cli -p "$REDIS_PORT" --rdb "$BACKUP_ROOT/redis/dump.rdb"

# 5. Create archive

tar -czvf "$BACKUP_ROOT/cubesandbox-backup-$(date +%F).tar.gz" -C "$BACKUP_ROOT" .

```

## Restoring from a Backup

To restore a CubeSandbox deployment to a fresh host:

1. **Extract the archive**: `tar -xzf cubesandbox-backup-YYYY-MM-DD.tar.gz -C /restore`
2. **Replace YAML files**: Copy the three files from `/restore/config/` to `configs/single-node/` in your new installation.
3. **Restore environment**: Copy `/restore/config/.env` to the repository root if it exists.
4. **Import databases**: `mysql -u<user> -p<pass> ossdb_config < /restore/mysql/ossdb.sql` and repeat for `instance_db_config`.
5. **Load Redis**: Stop the Redis container, replace its `dump.rdb` with `/restore/redis/dump.rdb`, then restart.
6. **Restart services**: Reload systemd units (`systemctl restart cube-sandbox-cubemaster.service`) or rerun the Docker Compose deployment.

## Summary

- **Backup the three YAML files** ([`cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubemaster.yaml), [`cubelet.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/cubelet.yaml), [`network-agent.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/network-agent.yaml)) from `configs/single-node/` to preserve static service parameters.
- **Preserve the `.env` file** to retain runtime overrides and credentials.
- **Export both MySQL databases** (`ossdb_config` and `instance_db_config`) using `mysqldump` to capture runtime metadata and state.
- **Optionally dump Redis** with `redis-cli --rdb` for complete metric history preservation.
- **Archive everything** into a versioned `tar.gz` file for portable disaster recovery.

## Frequently Asked Questions

### What files are essential for a minimal CubeSandbox backup?

The absolute minimum requires the three YAML files in `configs/single-node/` and the MySQL dumps for `ossdb_config` and `instance_db_config`. The `.env` file is essential only if you overrode default ports or credentials. Redis is optional unless you require historical metric data.

### How do I find the MySQL credentials for mysqldump?

Credentials are defined in [`configs/single-node/cubemaster.yaml`](https://github.com/TencentCloud/CubeSandbox/blob/main/configs/single-node/cubemaster.yaml) under the `ossdb_config` and `instance_db_config` sections. Look for the `user`, `pwd`, and `db_name` keys. Alternatively, check your `.env` file for `CUBE_SANDBOX_MYSQL_USER` and `CUBE_SANDBOX_MYSQL_PASSWORD` variables.

### Is Redis data mandatory to backup?

No. According to the TencentCloud/CubeSandbox source code, Redis stores node-metric keys and sandbox-proxy routing information that the system can rebuild automatically on restart. However, backing up Redis ensures you retain point-in-time metric snapshots and avoids cold-start performance penalties.

### Can I backup a multi-node CubeSandbox cluster the same way?

Yes, but you must repeat the YAML file backup for each node's `configs/` directory (though the files are typically identical). MySQL and Redis are usually centralized services, so a single backup of those databases covers the entire cluster. Ensure you capture the `.env` file from each host if node-specific overrides exist.