# How to Convert OCI Images to Sandbox Templates in CubeSandbox: A Three-Phase Workflow

> Learn the three-phase workflow for converting OCI images to CubeSandbox templates. Discover how CubeSandbox pulls layers, boots a MicroVM, and distributes artifacts for efficient sandbox management.

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

---

**CubeSandbox converts standard OCI container images into reusable sandbox templates through an asynchronous three-phase pipeline that pulls layers into an ext4 rootfs, boots a MicroVM for snapshotting, and distributes the artifacts cluster-wide.**

The TencentCloud/CubeSandbox project enables sub-second startup of isolated execution environments by transforming container images into specialized templates. Converting OCI images to sandbox templates involves a native streaming exporter that eliminates external tooling, a health-checked snapshotting process, and a distributed registration system. This workflow allows any HTTP-serving container to become a hot-startable sandbox template referenced by a unique `template_id`.

## The Three-Phase OCI to Template Conversion Pipeline

CubeSandbox implements an asynchronous pipeline that progresses through distinct phases tracked via job status. Each phase is orchestrated through specific functions in the `CubeMaster/pkg/templatecenter` package.

### Phase 1: Pull and Build the ext4 Rootfs

The conversion begins by streaming OCI image layers directly from the registry without external tools. In [`CubeMaster/pkg/templatecenter/image/native.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/image/native.go), the **`StreamRegistryToDir`** function fetches layers concurrently and unpacks them into an **ext4 rootfs** on the node. This native exporter avoids container runtime overhead by writing layers directly to disk when `nativeRootfsExportEnabled` is true.

```go
// Example: Stream an OCI image into a destination directory
ctx := context.Background()
src := &image.PreparedSource{
    // … fill with registry reference, auth, progress callbacks …
}
err := image.StreamRegistryToDir(ctx, src, "/var/lib/cubesandbox/templates/tmp")
if err != nil {
    log.Fatalf("failed to export image: %v", err)
}

```

### Phase 2: Boot and Snapshot the MicroVM

Once the rootfs is prepared, the system boots it inside a lightweight MicroVM. The **`runTemplateImageJob`** function in [`CubeMaster/pkg/templatecenter/template_image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/template_image.go) manages this phase, creating the VM and probing the container's HTTP server on the specified port and path. When the health check returns successfully, Cube captures a **memory snapshot** of the running VM, preserving the initialized state for instant restoration.

### Phase 3: Register and Distribute

The final phase stores the rootfs artifact and memory snapshot in the **Template Store**. The **`GetTemplateImageJobInfo`** function monitors distribution progress via **`overlayTemplateImageJobPullProgress`**, tracking how many nodes have received the template (displayed as "N/M ready"). Once distribution completes, the template reaches the `READY` state and becomes available for instantiation.

## CLI Workflow for OCI Conversion

End-users trigger conversions through the `cubemastercli` command-line tool. The process is asynchronous: submission returns immediately with a `job_id`, while monitoring commands track the pipeline through states: `PULLING → BUILDING → DISTRIBUTING → READY`.

Start the conversion by specifying the image, writable layer size, exposed ports, and health probe parameters:

```bash

# 1️⃣ Start the conversion (asynchronous)

cubemastercli tpl create-from-image \
  --image  registry.example.com/myapp:latest \
  --writable-layer-size 1G \
  --expose-port 8080 \
  --probe 8080 \
  --probe-path /health

```

Monitor the job until completion:

```bash

# 2️⃣ Watch progress (blocking)

cubemastercli tpl watch --job-id <job_id>

# 3️⃣ When the job shows `status: READY` you can use the template:

export CUBE_TEMPLATE_ID=tpl-xxxxxxxxxxxx
python -m CubeAPI.examples.create   # E2B SDK example

```

## Programmatic Integration with the Go SDK

Applications can submit template creation jobs directly using the Go API. The **`SubmitTemplateFromImage`** function accepts a configuration struct matching the CLI parameters:

```go
// Example: Submit a template‑creation job from Go (mirrors the CLI command)
req := &types.CreateTemplateFromImageReq{
    Image:               "registry.example.com/myapp:latest",
    WritableLayerSize:   "1G",
    ExposePort:          []int{8080},
    ProbePort:           8080,
    ProbePath:           "/health",
    TemplateID:          "tpl-12345",
    InstanceType:        "cubebox",
    NetworkType:         "default",
}
info, err := templatecenter.SubmitTemplateFromImage(ctx, req, "http://download.base.url")
if err != nil {
    log.Fatalf("submit failed: %v", err)
}
fmt.Printf("Job %s submitted, watching…\n", info.JobID)

```

## Key Implementation Files

The conversion workflow is implemented across these source files:

- **[`CubeMaster/pkg/templatecenter/template_image.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/template_image.go)** – Orchestrates the three-phase pipeline, stores job metadata, and provides status APIs including `runTemplateImageJob` and `GetTemplateImageJobInfo`.

- **[`CubeMaster/pkg/templatecenter/image/native.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/image/native.go)** – Contains the native OCI-layer streaming implementation and ext4 rootfs construction via `StreamRegistryToDir`.

- **`CubeMaster/pkg/templatecenter/image`** (directory) – Houses helper types (`PreparedSource`, progress structs) and utilities used by the exporter.

- **`CubeMaster/cmd/cubemastercli`** – Implements the `tpl create-from-image`, `tpl watch`, and `tpl status` commands.

- **[`docs/guide/tutorials/template-from-image.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/docs/guide/tutorials/template-from-image.md)** – User-facing documentation covering CLI usage and probing requirements.

## Summary

- **Submit** a conversion job using `cubemastercli tpl create-from-image` or the `SubmitTemplateFromImage` Go function.
- **Stream** OCI layers concurrently via `StreamRegistryToDir` in [`native.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/native.go) to build an ext4 rootfs without external tools.
- **Boot** the VM, **probe** the HTTP server for readiness, and capture a **memory snapshot** through `runTemplateImageJob`.
- **Register** artifacts in the Template Store and distribute to all nodes; the template becomes `READY` once distribution completes.
- **Reference** the resulting `template_id` in sandbox creation requests for hardware-isolated, hot-start instances.

## Frequently Asked Questions

### What are the requirements for an OCI image to be converted to a CubeSandbox template?

The OCI image **must expose an HTTP server** that responds to health checks. You must specify the `--probe` port and `--probe-path` during conversion so that `runTemplateImageJob` can determine when the container initialization is complete before capturing the memory snapshot.

### How do I monitor the progress of an OCI-to-template conversion job?

Use `cubemastercli tpl watch --job-id <job_id>` for blocking updates or `cubemastercli tpl status` for snapshots. The job progresses through phases: `PULLING`, `BUILDING`, `DISTRIBUTING`, and finally `READY`. The distribution status shows "N/M ready" indicating how many cluster nodes have received the template artifacts.

### Where in the source code does the rootfs construction from OCI layers occur?

The native streaming and ext4 construction happens in [`CubeMaster/pkg/templatecenter/image/native.go`](https://github.com/TencentCloud/CubeSandbox/blob/main/CubeMaster/pkg/templatecenter/image/native.go), specifically within the **`StreamRegistryToDir`** function. This implementation bypasses external container tools by fetching layers concurrently and writing them directly to an ext4 filesystem when `nativeRootfsExportEnabled` is configured.

### Can I trigger template creation programmatically without using the CLI?

Yes. Import the `templatecenter` package and call **`SubmitTemplateFromImage`** with a `CreateTemplateFromImageReq` struct containing your image reference, writable layer size, port exposures, and probe configuration. This returns a job ID that you can monitor through the API or CLI.