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

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, 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.

// 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 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:

# 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:

# 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:

// 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 – Orchestrates the three-phase pipeline, stores job metadata, and provides status APIs including runTemplateImageJob and GetTemplateImageJobInfo.

• 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 – 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}