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

> Learn to manage CubeSandbox environments using the WebUI console at port 12088. Access and control container sandboxes easily through your browser.

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

---

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

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

```

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

```bash
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:

```bash
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/api/client.ts), which sends `POST /api/v1/sandboxes`:

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

```typescript
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`:

```typescript
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/vite.config.ts) | Development server configuration and API proxy settings |
| [`web/src/api/client.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/api/client.ts) | Centralized HTTP client handling authentication headers |
| [`web/src/store/ui.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/docker/README.md) | Default credentials and environment setup instructions |

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

```env
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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/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`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/vite.config.ts), ensuring the `VITE_API_BASE` variable points to your Cubelet API endpoint.