# How to Use the CubeSandbox WebUI: Complete Dashboard Management Guide

> Master the CubeSandbox WebUI for complete dashboard management. Visually control clusters, sandboxes, and templates via automatic proxying to CubeAPI. Simplify your workflow today.

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

---

**The CubeSandbox WebUI is a built-in React application served on port 12088 that provides visual management of clusters, sandboxes, and templates through automatic proxying to the CubeAPI backend, eliminating the need for manual curl commands.**

The CubeSandbox WebUI (also referred to as the *Dashboard*) serves as the primary graphical interface for the TencentCloud/CubeSandbox platform. This static frontend runs inside an nginx container on the control node and communicates with the backend via `/cubeapi/v1/*` endpoints, allowing you to perform everyday operations without interacting with the SDK or CLI directly.

## Accessing the CubeSandbox WebUI

After completing the CubeSandbox installation, the WebUI is reachable at `http://<control-node-IP>:12088`. The API itself listens on port 3000, but the UI automatically proxies all calls, so you only need to interact with the dashboard URL.

When running the development server locally, the interface is available at `http://localhost:5173`. This Vite-based development environment provides hot-reload capabilities for customizing the interface.

## Authenticating with API Keys

If your deployment has authentication enabled, you must configure your credentials before accessing resources.

1. Open **API Keys** in the left navigation rail.
2. Paste your generated `sk-cube-…` secret key into the input field.
3. Click **Save** to store the credentials.

The key is persisted only in your browser's `localStorage` and is sent with subsequent API requests to authenticate your session.

## Navigating the Dashboard Interface

The WebUI organizes functionality through a left sidebar containing 11 navigation icons, including Overview, Sandboxes, Templates, and Settings. Hovering over each icon reveals its label, while clicking loads the corresponding page component.

The routing logic is defined in [`web/src/main.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/main.tsx), where the React Router configuration wraps protected routes inside an `AuthGuard` component and renders the layout through `AppShell`:

```tsx
import { BrowserRouter, Routes, Route, Navigate } from 'react-router-dom';
import { AuthGuard } from '@/components/AuthGuard';
import { AppShell } from '@/components/AppShell';
import OverviewPage from '@/pages/Overview';
import SandboxesPage from '@/pages/Sandboxes';
import SandboxNewPage from '@/pages/SandboxNew';
import TemplateDetailPage from '@/pages/TemplateDetail';

const App = () => (
  <BrowserRouter>
    <Routes>
      <Route path="/login" element={<LoginPage />} />
      <Route element={<AuthGuard />}>
        <Route element={<AppShell />}>
          <Route path="/" element={<OverviewPage />} />
          <Route path="/sandboxes" element={<SandboxesPage />} />
          <Route path="/sandboxes/new" element={<SandboxNewPage />} />
          <Route path="/templates/:templateID" element={<TemplateDetailPage />} />
          <Route path="*" element={<Navigate to="/" replace />} />
        </Route>
      </Route>
    </Routes>
  </BrowserRouter>
);

```

The `AppShell` component in [`web/src/components/AppShell.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/components/AppShell.tsx) provides the global layout structure, rendering the left rail, top navigation bar, and content outlet where page components mount.

## Managing Cluster Resources

### Monitoring Health via the Overview Page

The **Overview** page (`/`) serves as the dashboard home, displaying real-time KPI cards for running sandboxes, CPU and memory utilization, and node health status. According to the source code in [`web/src/pages/Overview.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Overview.tsx), this data is fetched using React Query with specific refetch intervals to maintain live visibility:

```tsx
const cluster = useQuery({ 
  queryKey: ['cluster'], 
  queryFn: clusterApi.overview, 
  refetchInterval: 10_000 
});
const sandboxes = useQuery({ 
  queryKey: ['sandboxes'], 
  queryFn: () => sandboxApi.list(), 
  refetchInterval: 5_000 
});
const templates = useQuery({ 
  queryKey: ['templates'], 
  queryFn: templateApi.list, 
  refetchInterval: 30_000 
});

```

The cluster overview updates every 10 seconds, sandbox lists refresh every 5 seconds, and template data updates every 30 seconds.

### Creating and Managing Sandboxes

To create a new sandbox through the WebUI:

1. Click **Sandboxes** in the left rail, then select **+ New sandbox**.
2. Choose a `READY` template from the displayed grid (templates are queried from the Template Store).
3. Optionally add meta key/value pairs for labeling.
4. Click **Create** to submit the request.

The UI handles the creation flow through the sandbox API and automatically redirects to the new sandbox's detail page where logs stream in real time:

```tsx
<Button onClick={handleCreate}>Create</Button>

async function handleCreate() {
  await sandboxApi.create({ templateID: selectedTemplate });
  // Navigation to /sandboxes/<new-id> occurs automatically
}

```

### Managing Templates

The **Template Store** page allows you to install official preset images, while the **Templates** page displays each template's build status, version history, and configuration details. You can inspect specific templates by clicking through to the detail view defined in [`web/src/pages/TemplateDetail.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/TemplateDetail.tsx).

## Keyboard Shortcuts and UI Customization

The CubeSandbox WebUI supports several keyboard shortcuts for power users:

- **⌘K / Ctrl+K**: Open the command palette for quick navigation.
- **?**: Display the full shortcuts list.
- **R**: Refetch all active data queries.
- **Esc**: Close open modals or panels.

In the **Settings** page, you can toggle between light and dark themes, change the interface language, and view read-only cluster information. The theme context is provided by [`web/src/components/ThemeProvider.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/components/ThemeProvider.tsx) and applied globally via the `AppShell` component.

## Building the WebUI from Source

If you need to customize the interface or run an independent instance, the source code resides in the `web/` directory. The project uses **Vite** + **React** + **TypeScript** + **Tailwind CSS** for styling.

To build your own version:

1. Navigate to the `web/` directory.
2. Install dependencies and run the development server following the instructions in [`web/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/README.md).
3. Build static assets for production deployment.

The resulting build can be served by any static file server or containerized with nginx as implemented in the default deployment.

## Summary

- The CubeSandbox WebUI runs on port 12088 (production) or 5173 (development) and automatically proxies API calls to the backend on port 3000.
- Authentication uses `sk-cube-…` API keys stored in browser `localStorage`, configured through the left sidebar.
- The interface is built with React and React Query, with specific polling intervals (5s, 10s, 30s) for different data types as defined in [`web/src/pages/Overview.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Overview.tsx).
- Key source files include [`web/src/main.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/main.tsx) for routing, [`web/src/components/AppShell.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/components/AppShell.tsx) for layout, and [`web/src/pages/Overview.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Overview.tsx) for the dashboard home.
- Keyboard shortcuts (⌘K, ?, R, Esc) and theme settings are available through the Settings page.

## Frequently Asked Questions

### What port does the CubeSandbox WebUI use by default?

The WebUI listens on port **12088** in standard deployments, served by nginx on the control node. During development, the Vite dev server runs on port **5173**. The backend API operates separately on port 3000, but the WebUI handles proxying automatically so you only interact with the dashboard URL.

### How does the WebUI store authentication credentials?

When you enter an API key in the **API Keys** section, the value is stored exclusively in your browser's `localStorage` under the key `cube-api-key`. The credential is never persisted server-side; it is retrieved from local storage and attached to API request headers for each backend call requiring authentication.

### Can I modify or self-host the CubeSandbox WebUI independently?

Yes, the entire frontend source is located in the `web/` directory of the repository. It uses standard React patterns with Vite for building and Tailwind for styling. You can build a custom version by following the instructions in [`web/README.md`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/README.md), then deploy the static output to any web server or containerize it with nginx as done in the official distribution.

### Why does the Overview page refresh automatically?

The Overview page in [`web/src/pages/Overview.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Overview.tsx) implements automatic polling via React Query's `refetchInterval` option. Cluster health data refreshes every 10 seconds, sandbox lists every 5 seconds, and template data every 30 seconds. This ensures the dashboard displays near-real-time status without requiring manual page reloads.