How to Use the CubeSandbox WebUI Console at Port 12088 for Sandbox Management

The CubeSandbox WebUI console is a React-based management interface that exposes port 12088 by default, enabling you to create, monitor, snapshot, and terminate sandbox instances through an intuitive browser-based graphical interface.

The CubeSandbox repository from TencentCloud provides a containerized sandbox environment with a comprehensive WebUI console. This browser-based interface, accessible at port 12088, eliminates the need for command-line operations by providing complete sandbox lifecycle management through React-powered pages.

Architecture Overview

The WebUI is built as a Vite-powered React application that communicates with the Cubelet back-end. The architecture separates presentation logic from state management through dedicated stores and API clients.

Key Components:

• web/vite.config.ts – Configures the development server and production build, including the proxy settings for API calls to the Cubelet back-end.

• web/src/pages/Sandboxes.tsx – Main listing page displaying all sandbox instances with sorting, filtering, and bulk action capabilities.

• web/src/pages/SandboxDetail.tsx – Detailed view showing runtime metrics, console logs, snapshot history, and instance controls for a specific sandbox.

• web/src/pages/Observability.tsx – Real-time metrics dashboard displaying CPU, memory, and network utilization charts.

• web/src/api/client.ts – Centralized HTTP client that wraps REST API calls to /api/v1/ endpoints, handling authentication headers and error responses.

• web/src/store/ui.ts – State management store responsible for the JWT authentication token, selected sandbox ID, and global loading states.

• web/src/store/theme.ts – Manages UI appearance settings including color schemes and layout preferences.

• web/src/components/AuthGuard.tsx – Route guard component that validates authentication status before rendering protected pages.

• docker/Dockerfile.builder – Container definition that builds the static assets and exposes port 12088 for the web server.

Accessing the WebUI Console

To access the sandbox management interface, you must first start the WebUI service and expose port 12088.

Option 1: Docker Deployment (Recommended)

# Build the UI image from the repository root

docker build -f docker/Dockerfile.builder -t cubesandbox-webui .

# Run the container, mapping port 12088

docker run -d -p 12088:12088 --name cubesandbox-ui cubesandbox-webui

Option 2: Local Development

cd web
npm install
npm run dev

The Vite development server launches on http://localhost:12088 by default, as configured in the vite settings.

Once the service is running, navigate to http://localhost:12088 in your browser. The AuthGuard.tsx component will redirect unauthenticated users to the login screen. Enter the credentials configured in your Cubelet back-end (default credentials are typically documented in docker/README.md).

Managing Sandboxes Through the Console

After authentication, the WebUI provides full lifecycle management capabilities through the React page components.

Creating a New Sandbox

Click "New Sandbox" on the Sandboxes.tsx list page. The creation form collects:

• Sandbox name
• Container image reference
• CPU and memory limits

When submitted, the client.ts module sends a POST request to /api/v1/sandboxes:

// From web/src/api/client.ts
export async function createSandbox(payload: {
  name: string;
  image: string;
  cpu: number;
  memory: number;
}) {
  const resp = await fetch(
    `${import.meta.env.VITE_API_BASE}/api/v1/sandboxes`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${uiStore.token}`,
      },
      body: JSON.stringify(payload),
    }
  );
  return resp.json();
}

Viewing Sandbox Details

Click any sandbox row to open SandboxDetail.tsx. This page displays:

• Real-time resource utilization charts
• Container stdout/stderr logs streaming
• Network configuration and port mappings
• Active snapshot list

Taking Snapshots

In the detail view, click "Snapshot" to create a point-in-time backup. The UI sends a POST request to /api/v1/sandboxes/{id}/snapshots:

// Snapshot creation implementation
export async function takeSnapshot(
  sandboxId: string,
  snapshotName: string
) {
  return fetch(
    `${import.meta.env.VITE_API_BASE}/api/v1/sandboxes/${sandboxId}/snapshots`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${uiStore.token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ name: snapshotName }),
    }
  );
}

Rolling Back to Previous States

Select a snapshot from the history list in SandboxDetail.tsx and click "Rollback". This invokes the restoration endpoint:

// Rollback implementation from web/src/api/client.ts
export async function rollbackSandbox(
  sandboxId: string,
  snapshotId: string
) {
  return fetch(
    `${import.meta.env.VITE_API_BASE}/api/v1/sandboxes/${sandboxId}/rollback`,
    {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${uiStore.token}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ snapshot_id: snapshotId }),
    }
  );
}

Deleting Sandboxes

Use the trash icon on the Sandboxes.tsx list or the Delete button on the detail page. This triggers a DELETE request to /api/v1/sandboxes/{id} via the API client.

Configuration and Customization

The WebUI supports environment-based configuration through the web/.env file or runtime environment variables:

VITE_API_BASE=http://localhost:8080
VITE_PORT=12088

Global appearance settings are managed in web/src/store/theme.ts, while authentication state persists through web/src/store/ui.ts.

Summary

• The CubeSandbox WebUI console runs on port 12088 and provides a React-based interface for sandbox management.
• The architecture uses Vite for building, React pages for UI views, and a centralized API client (web/src/api/client.ts) for back-end communication.
• Authentication is enforced by AuthGuard.tsx, requiring valid JWT tokens stored in the UI state.
• Core operations include creating sandboxes, viewing details in SandboxDetail.tsx, taking snapshots, rolling back to previous states, and deleting instances.
• Deployment is streamlined through docker/Dockerfile.builder, which exposes port 12088 for browser access.

Frequently Asked Questions

What is the default port for the CubeSandbox WebUI console?

The WebUI console listens on port 12088 by default. This is configured in the Vite development server settings and exposed in the Docker container through docker/Dockerfile.builder. You can override this by setting the VITE_PORT environment variable before starting the service.

How does the WebUI authenticate with the Cubelet back-end?

The AuthGuard.tsx component validates the JWT token stored in web/src/store/ui.ts. Upon login, the UI receives a token from the Cubelet API (/api/v1/auth/login) and stores it in the global state. The client.ts module automatically includes this token in the Authorization header of all subsequent API requests.

Can I manage sandboxes without using the WebUI console?

Yes. While the WebUI provides a convenient graphical interface, all operations performed through the React pages ultimately call the Cubelet REST API directly. You can interact with the same endpoints (/api/v1/sandboxes, /api/v1/snapshots, etc.) using curl, HTTP clients, or the CubeSandbox CLI if you prefer programmatic access.

Where are the WebUI source files located in the repository?

The React application resides in the web/ directory at the repository root. Key subdirectories include:

• web/src/pages/ – React components for list and detail views
• web/src/api/ – API client implementations
• web/src/store/ – State management for UI and themes
• web/src/components/ – Reusable UI components including authentication guards

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