Offline Deployment

When to use this guide: your target nodes have no public internet access (intranet data centers, isolated network segments, restricted environments), and you need to deploy CubeSandbox offline. Such nodes usually sit on an intranet with mirror sources configured.

Offline deployment works. Prepare the items below, then install as you normally would. The install steps are identical to a normal deployment.

What to prepare	How	Where
The bundle (plus the optional PVM kernel package)	Download from Releases on a public-network machine, copy it over	Step 1
OS packages (Docker, Compose, …)	Skip if an internal mirror exists; manual install only without one	Step 2
Container images (the core)	Pull and pack on a public-network machine then docker load, or push to an internal registry	Step 3
Template source images (optional)	Push to the internal registry, reference it when creating templates	Step 5

With the first three prepared, install via Step 4; push the template source images after the install (Step 5).

Scope

This guide covers the one-click deployment (single-node, bare-metal, and multi-node cluster). Two deployment paths are out of scope:

• Terraform Tencent Cloud deployer: it creates cloud resources and needs Tencent Cloud API access.
• Kubernetes (Helm) deployment: the cluster must reach a container registry holding the component images. With an internal registry (e.g. Harbor), follow the Kubernetes deployment guide and point the chart at it.

Why offline works (the mechanics)

The one-click installer supports offline installs natively:

• Pre-loaded container images are used as-is — no script changes needed.
• The bundle ships every version-locked artifact (component binaries, vmlinux, guest image, mkcert).
• A normal deployment needs the public internet for exactly three things: the bundle, missing OS packages, and container images. They map to Steps 1–3 — whatever your internal mirrors cover stays on the intranet; prepare the rest in advance.

Before you start: host requirements

The host requirements are identical to a normal deployment (see Quick Start — Prerequisites):

• x86_64 or aarch64 Linux, glibc ≥ 2.31, root access
• At least 8 GB RAM (a hard installer check — the install aborts below it)
• XFS at /data/cubelet, at least 50 GB
• KVM available: native on bare metal; x86_64 cloud VMs can install the PVM kernel first (Step 1, no aarch64 support — ARM machines must already have KVM)

Step 1: Download the release artifacts

What to do: on a public-network machine, download the artifacts below and copy them to the target node. An internal artifact relay or a mirrored Releases channel works just as well.

1. The one-click bundle: cube-sandbox-one-click-<version>-<arch>.tar.gz. Pick the <arch> that matches the target node (amd64 / arm64); for download channels see Downloads & Releases.
2. The PVM host kernel package (rpm/deb): only if the target is a cloud VM without /dev/kvm. Download it from the newest kernel-release-* release, install and reboot per PVM Deployment — Step 1, then come back to this guide.

Move the files to the target node with scp, a USB drive, or similar.

Step 2: Pre-install the OS packages (no internal mirror only)

Have an internal OS mirror? Skip to Step 3.

Only a machine with no internal mirror at all needs this step: download the packages below on a public-network machine, copy them over, and install.

Package list (click to expand)

Before skipping, confirm the mirror carries Docker and Compose — many internal mirrors omit them.

Every node needs:

• Docker Engine and Compose. As long as both docker and docker compose version (or docker-compose) work, install.sh skips the online install. Verify after installing:

  docker version && docker compose version   # or: docker-compose --version

  ⚠️ Snap Docker is rejected (it cannot read /usr/local/services). Install docker-ce / docker.io from packages instead.

• Basic commands: tar, ss, ip (iproute2), bash, curl, grep, sed, pgrep (procps), awk, date, openssl

• e2fsprogs + util-linux: the default cubecow storage backend needs mkfs.ext4, mount, umount, losetup

Only when applicable:

• dnsmasq: required when the host has no systemd-resolved/resolvectl — otherwise the DNS fallback installs it automatically
• s3fs + jq: S3 volume mount dependencies. The installer tries to auto-install them; a failure stays silent until volume attach — install them in advance
• python3, nvme-cli, libaio, libnuma, libuuid: only if you enable CubeS3lvol (ONE_CLICK_ENABLE_S3LVOL=1)
• logrotate: add it if your minimal image does not ship it

Step 3: Pre-load the container images

What to do: get the images from Step 3.1 onto the target node's local Docker. Pick either path:

• Hand-carry per node (the example below): on a public-access machine of the same architecture as the target, docker pull → docker save → docker load on the target.
• Via an internal registry (recommended for many nodes): push the images to the internal registry (e.g. Harbor) and point the override variables at it. The installer pulls from there directly — no per-node loading.

Commands for the hand-carry path:

# Public-network machine: pull every image from the list
docker pull <image-ref>

# Pack per node role (keeps transfers small)
docker save -o cube-images-control.tar <image-1> <image-2> ...

# Target node
docker load -i cube-images-control.tar

3.1 Which images each node needs

Control node (the default all-in-one install.sh, or every control node of a cluster):

Image	Default reference	Override variable
MySQL	cube-sandbox-image.tencentcloudcr.com/opensource/mysql:8.0	CUBE_SANDBOX_MYSQL_IMAGE
Redis	cube-sandbox-image.tencentcloudcr.com/opensource/redis:7-alpine	CUBE_SANDBOX_REDIS_IMAGE
MinIO (S3 backend, on by default)	cube-sandbox-int.tencentcloudcr.com/cube-sandbox/minio:<release>	CUBE_SANDBOX_MINIO_IMAGE
CoreDNS	cube-sandbox-image.tencentcloudcr.com/opensource/coredns/coredns:1.14.2	CUBE_PROXY_COREDNS_IMAGE
WebUI (nginx)	cube-sandbox-image.tencentcloudcr.com/opensource/openresty:1.21.4.1-6-alpine-fat	WEB_UI_IMAGE
cube-proxy	cube-sandbox-int.tencentcloudcr.com/cube-sandbox/cube-proxy:<tag>	CUBE_SANDBOX_CUBE_PROXY_IMAGE
cube-lifecycle-manager	cube-sandbox-int.tencentcloudcr.com/cube-sandbox/cube-lifecycle-manager:<tag>	CUBE_SANDBOX_CUBE_LCM_IMAGE
cube-egress	cube-sandbox-int.tencentcloudcr.com/cube-sandbox/cube-egress:<tag>	CUBE_SANDBOX_CUBE_EGRESS_IMAGE

Compute node (install-compute.sh):

Image	Default reference	Notes
cube-egress	same as above	mandatory — the egress MITM proxy runs on every node
JuiceFS mount	cube-sandbox-int.tencentcloudcr.com/cube-sandbox/juicefs:ce-v1.4.1	only if ONE_CLICK_ENABLE_JFS=1; MIRROR=cn selects the -cn host

The <tag> / <release> placeholders for cube-proxy / cube-lifecycle-manager / cube-egress / MinIO resolve with this command, run from the extracted bundle root:

grep -rhE '_IMAGE.*_DEFAULT="' scripts/

3.2 The reference must match exactly

• If you pulled the -cn references, set MIRROR=cn in .env; if you pulled -int, leave MIRROR unset.
• For an internal registry or your own image names, point the override variables above at them in .env.

3.3 Verify on the target node

docker images   # every reference from the list must appear, same name and tag

Step 4: Install — exactly like a normal deployment

What to do: install exactly as you would online, except you run the transferred bundle instead of the online installer command.

Every command must run as root. Switch to root first:

sudo su root

Extract the bundle and install:

tar -xzf cube-sandbox-one-click-<version>-<arch>.tar.gz
cd cube-sandbox-one-click-<version>-<arch>
cp env.example .env
# edit .env if needed (node IP, external MySQL/Redis, MIRROR, image overrides…)
./install.sh

Pick your scenario:

• Cloud VM without /dev/kvm (PVM): follow Quick Start, swapping only its Step 2 (online install) for the bundle command above — everything else stays as written.
• Bare metal / machines with KVM: see Bare-Metal Deployment.
• Adding compute nodes: see Multi-Node Cluster. The bundle is reused as-is; a compute node only needs the cube-egress image pre-loaded (Step 3.1).

After the install, verify as usual:

./smoke.sh

The dashboard is at http://<target-host>:12088 and the E2B-compatible API is on port 3000 (Quick Start — Step 4).

What the logs look like offline

When the registry is unreachable, the three component images each log WARN: pull failed but local image exists; using cached copy and use your pre-loaded image; the other services use theirs silently. All expected, not errors. Only pull failed … and no local copy is cached means an image was never loaded — go back to Step 3.

Step 5 (after install, optional): Push template source images into the internal registry

What to do: if you want to create templates offline, push the template source images to your internal registry, then reference that registry when creating templates.

Why: CubeMaster pulls the source image from a registry when building a template — an internal registry is all it needs, no public internet. Multi-node clusters need nothing extra: CubeMaster distributes artifacts over the intranet; compute nodes never pull the source image.

Two steps:

1. Push the source image into the internal registry. Pull and pack it on a public-network machine, then transfer it to a machine that can reach the internal registry (the control node, for example), and load / tag / push there — the official code-interpreter image for example:

   # Public-network machine
   docker pull cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest
   docker save -o sandbox-code.tar cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest
   
   # Machine that can reach the internal registry
   docker load -i sandbox-code.tar
   docker tag cube-sandbox-int.tencentcloudcr.com/cube-sandbox/sandbox-code:latest \
     <internal-registry>/cube/sandbox-code:latest
   docker push <internal-registry>/cube/sandbox-code:latest

2. Create the template with the internal registry reference (see Quick Start — Step 3):

   cubemastercli tpl create-from-image \
     --image <internal-registry>/cube/sandbox-code:latest \
     --writable-layer-size 1G \
     --expose-port 49999 \
     --expose-port 49983 \
     --probe 49999

Two details:

• If the internal registry requires authentication, add --registry-username / --registry-password.
• If it serves plain HTTP (no TLS), the reference must carry an http:// prefix, e.g. http://harbor.internal:5000/ns/app:tag.

You can also skip the internal registry and use a local image — full recipe in the run-code-env-inheritance example.

Upgrades, template builds, and uninstall

• Upgrading = a new bundle + a new image set (tags advance with each release). Repeat Step 1 and Step 3 for the new version, then run ./install.sh --mode=upgrade (see one-click README — Target Machine Installation).
• Building custom template images offline: a Dockerfile build usually needs apt/pip. Point those at your internal mirrors, or bake a complete image while still on a public network and push it into the internal registry as in Step 5 (recipes in Local & Remote Image Practice — Troubleshooting).
• Uninstall is unchanged: /usr/local/services/cubetoolbox/scripts/one-click/uninstall.sh.

Troubleshooting

Symptom	Cause	Fix
pull failed for <ref> and no local copy is cached	The loaded image reference does not match what the installer resolves (wrong tag or registry variant)	Compare docker images with the bundle's default references (env.example, or the grep output from Step 3.1); check MIRROR consistency (Step 3.2)
docker missing; installer runs apt-get/yum install docker and fails	The internal mirror does not carry Docker, and it was not pre-installed	Add Docker to the internal mirror, or pre-install Docker Engine + Compose (Step 2)
Installer aborts over snap Docker	snap install docker sandboxing cannot read /usr/local/services	sudo snap remove docker, install docker-ce from packages
Install aborts installing dnsmasq	Host lacks systemd-resolved and the internal mirror cannot install dnsmasq	Add dnsmasq to the internal mirror or pre-install it; or use an OS with systemd-resolved
Template build stuck in phase: PULLING	The --image reference is missing from the internal registry, or CubeMaster cannot reach it	Confirm the image was pushed and the reference is right; check the http:// prefix for HTTP registries; add --registry-username / --registry-password if the registry requires auth