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

> Master sandbox management with the CubeSandbox WebUI console on port 12088. Easily create, monitor, snapshot, and terminate instances via an intuitive browser interface.

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

---

**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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Sandboxes.tsx)** – Main listing page displaying all sandbox instances with sorting, filtering, and bulk action capabilities.

- **[`web/src/pages/SandboxDetail.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Observability.tsx)** – Real-time metrics dashboard displaying CPU, memory, and network utilization charts.

- **[`web/src/api/client.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/store/theme.ts)** – Manages UI appearance settings including color schemes and layout preferences.

- **[`web/src/components/AuthGuard.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/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)**

```bash

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

```bash
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/Sandboxes.tsx) list page. The creation form collects:
- Sandbox name
- Container image reference
- CPU and memory limits

When submitted, the **[`client.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/client.ts)** module sends a `POST` request to `/api/v1/sandboxes`:

```typescript
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`:

```typescript
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/SandboxDetail.tsx) and click **"Rollback"**. This invokes the restoration endpoint:

```typescript
// 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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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:

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

```

Global appearance settings are managed in **[`web/src/store/theme.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/store/theme.ts)**, while authentication state persists through **[`web/src/store/ui.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/api/client.ts)) for back-end communication.
- Authentication is enforced by **[`AuthGuard.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/AuthGuard.tsx)**, requiring valid JWT tokens stored in the UI state.
- Core operations include creating sandboxes, viewing details in **[`SandboxDetail.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/AuthGuard.tsx)** component validates the JWT token stored in **[`web/src/store/ui.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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