How to Use the CubeSandbox WebUI: Complete Dashboard Management Guide

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, where the React Router configuration wraps protected routes inside an AuthGuard component and renders the layout through AppShell:

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 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, this data is fetched using React Query with specific refetch intervals to maintain live visibility:

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:

<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.

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 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.
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.
• Key source files include web/src/main.tsx for routing, web/src/components/AppShell.tsx for layout, and 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, 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 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.

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