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

The CubeSandbox WebUI console runs as a React application that maps host port 12088 to the container's internal service port, providing authenticated access to create, monitor, and manage container sandboxes through a browser-based interface.

CubeSandbox is an open-source sandbox management system maintained by TencentCloud. The WebUI console, located in the web/ directory of the repository, offers a graphical alternative to CLI tools for interacting with the Cubelet backend. When deployed via Docker, the interface is accessible on port 12088 by mapping it to the container's exposed port.

Architecture and Key Components

The WebUI architecture separates presentation, state management, and API communication into distinct layers.

Vite Dev Server: The web/vite.config.ts file configures the development server port and proxy rules for routing API requests to the Cubelet backend during local development.

React Page Components: The main sandbox list interface resides in web/src/pages/Sandboxes.tsx, while individual sandbox details, logs, and snapshot management render through companion components in the same directory.

State Management: Authentication tokens and global UI state persist in web/src/store/ui.ts. The AuthGuard component (web/src/components/AuthGuard.tsx) validates this state before granting access to management routes.

API Client: All HTTP requests route through web/src/api/client.ts, which automatically injects bearer tokens and handles the base URL configuration pointing to the Cubelet REST API.

Starting the Console on Port 12088

The Docker configuration exposes the service internally on port 18088, which you should map to port 12088 on your host machine.

Docker Deployment

Pull and run the pre-built image with the port mapping:

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

Alternatively, build locally using the repository's builder configuration:

docker build -f docker/Dockerfile.builder -t cubesandbox-ui .
docker run -d -p 12088:18088 --name cubesandbox-ui cubesandbox-ui

Local Development

For development with hot-reload on port 12088:

cd web
npm install
npm run dev -- --port 12088

Ensure the VITE_API_BASE environment variable in your .env file points to the running Cubelet instance before starting the dev server.

Authenticating to the Console

Upon accessing http://localhost:12088, the application redirects to a login screen. Validating credentials against POST /api/v1/auth/login, the login flow stores the returned JWT in web/src/store/ui.ts for subsequent request authentication.

Protected routes use the AuthGuard component to intercept navigation and verify token validity, ensuring only authenticated users can access sandbox management functions.

Managing Sandboxes Through the UI

Once authenticated, the console provides full lifecycle management through the following workflows.

Creating New Sandboxes

Click New Sandbox on the dashboard to open the creation form. This invokes the createSandbox function in web/src/api/client.ts, which sends POST /api/v1/sandboxes:

export async function createSandbox(payload: {
  name: string;
  image: string;
  cpu: number;
  memory: number;
}) {
  const resp = await fetch(`${process.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();
}

Monitoring and Logs

Select any sandbox row from the list in web/src/pages/Sandboxes.tsx to open the detail view. This component fetches runtime metrics and streams console logs from the Cubelet backend, displaying real-time CPU, memory, and network utilization charts.

Snapshot Operations

To preserve a sandbox state, click Snapshot in the detail view. This triggers the takeSnapshot method:

export async function takeSnapshot(sandboxId: string, snapshotName: string) {
  return fetch(
    `${process.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 }),
    },
  );
}

Rollback and Recovery

Restore a previous state by selecting a snapshot from the list and clicking Rollback, which executes POST /api/v1/sandboxes/{id}/rollback:

export async function rollbackSandbox(
  sandboxId: string,
  snapshotId: string,
) {
  return fetch(
    `${process.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

Remove instances using the delete action available in the sandbox list or detail view. This sends DELETE /api/v1/sandboxes/{id} via the API client to terminate the sandbox and release associated resources.

Configuration Reference

File	Purpose
web/vite.config.ts	Development server configuration and API proxy settings
web/src/api/client.ts	Centralized HTTP client handling authentication headers
web/src/store/ui.ts	JWT token storage and global UI state management
docker/Dockerfile.builder	Container build instructions exposing internal port 18088
docker/README.md	Default credentials and environment setup instructions

Override default settings by creating a .env file in the web/ directory:

VITE_API_BASE=http://localhost:8080

Summary

• Deploy the container with -p 12088:18088 to expose the console on port 12088 as defined in docker/Dockerfile.builder
• Authenticate through the login flow, which stores tokens in web/src/store/ui.ts for use across all API calls
• Create sandboxes via the dashboard using POST /api/v1/sandboxes implemented in web/src/api/client.ts
• Manage snapshots and rollbacks through the detail view using the dedicated snapshot and rollback endpoints
• Monitor resource usage in real-time through the metrics integration in web/src/pages/Sandboxes.tsx and related detail components

Frequently Asked Questions

Why is the console not responding on port 12088?

Verify that you started the container with the port mapping -p 12088:18088 and that port 12088 is not already in use on your host. The internal port 18088 is exposed by docker/Dockerfile.builder, so the mapping is required to access the service externally.

How do I change the backend API endpoint?

Set the VITE_API_BASE environment variable in a .env file within the web/ directory, or modify the proxy configuration in web/vite.config.ts before building. This redirects all API calls from the UI to your specified Cubelet instance.

Where are the default login credentials documented?

The docker/README.md file contains the default administrator username and password for initial console access. These credentials authenticate against the Cubelet backend when you first access the UI at http://localhost:12088.

Can I run the WebUI without Docker?

Yes. Install dependencies with npm install in the web/ directory and run npm run dev. Configure the Vite server to use port 12088 by passing the --port 12088 flag or modifying web/vite.config.ts, ensuring the VITE_API_BASE variable points to your Cubelet API endpoint.

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