# How the CubeSandbox Web Console Provides Visual Sandbox Management on Port 5173

> Manage sandboxes visually with the CubeSandbox web console on port 5173. Get real-time insights and interactive controls for your sandboxes.

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

---

**The CubeSandbox web console is a React-based single-page application served on port 5173 that delivers real-time visual sandbox management through automated polling, proxy-based API integration, and interactive lifecycle controls.**

The TencentCloud/CubeSandbox repository includes a browser-based management interface that eliminates the need for command-line interaction when managing isolated sandbox environments. Built with **React** and **Vite**, this web console provides operators with a continuous real-time view of all sandbox instances running within the cluster. The interface combines automated data fetching with intuitive controls for creating, monitoring, and controlling sandboxes through a unified visual dashboard.

## Console Architecture and Port Configuration

The web console architecture centers on a Vite development server configuration that bridges the React frontend with the CubeAPI backend services.

### Vite Development Server Setup

In [`web/vite.config.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/vite.config.ts), the development server runs explicitly on port 5173 and proxies API requests to the backend CubeAPI service. This configuration ensures that all HTTP calls to `/cubeapi` endpoints transparently forward to `http://127.0.0.1:3000`, eliminating CORS issues during development.

```typescript
// web/vite.config.ts
export default defineConfig({
  server: {
    port: 5173,               // Web console accessible at http://localhost:5173
    proxy: {
      '/cubeapi': 'http://127.0.0.1:3000', // Forward API calls to CubeAPI
    },
  },
});

```

### React Frontend Structure

The user interface resides in `web/src/pages` and implements a single-page application architecture using `react-router-dom`. The primary sandbox management view lives in [`Sandboxes.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/Sandboxes.tsx), while specialized views for creation ([`SandboxNew.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/SandboxNew.tsx)) and detailed inspection ([`SandboxDetail.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/SandboxDetail.tsx)) handle specific workflows. The UI relies on a component library including `Badge`, `Button`, and `Card` primitives to maintain consistent visual styling across the console.

## Real-Time Data Synchronization

Visual sandbox management requires continuous state synchronization between the browser and the CubeAPI backend. The console implements this through **React-Query** polling mechanisms and typed API clients.

### Automated Polling with React-Query

The `useQuery` hook in [`web/src/pages/Sandboxes.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Sandboxes.tsx) establishes a persistent connection to the sandbox list endpoint, refreshing data every 5 seconds to ensure the UI reflects the current cluster state. This automatic refetching eliminates manual page refreshes while providing operators with up-to-the-second visibility into sandbox health and resource utilization.

```typescript
// web/src/pages/Sandboxes.tsx
const { data, isLoading } = useQuery({
  queryKey: ['sandboxes', stateFilter],
  queryFn: () =>
    sandboxApi.list({ state: stateFilter === 'all' ? undefined : stateFilter }),
  refetchInterval: 5_000,   // Auto-refresh every 5 seconds
});

```

### Typed API Client Layer

The [`web/src/api/client.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/api/client.ts) file defines a typed `sandboxApi` object that abstracts HTTP interactions with the CubeAPI. This client exposes methods including `list`, `pause`, `resume`, and `kill`, each returning strongly-typed responses that the React components consume directly.

```typescript
// web/src/api/client.ts
export const sandboxApi = {
  async list(params?: { state?: string }) {
    const resp = await fetch(`/cubeapi/sandboxes${params?.state ? `?state=${params.state}` : ''}`);
    return (await resp.json()) as RunningSandbox[];
  },
  async kill(id: string) { 
    return fetch(`/cubeapi/sandboxes/${id}/kill`, { method: 'POST' }); 
  },
  async pause(id: string) { 
    return fetch(`/cubeapi/sandboxes/${id}/pause`, { method: 'POST' }); 
  },
  async resume(id: string) { 
    return fetch(`/cubeapi/sandboxes/${id}/resume`, { method: 'POST' }); 
  },
};

```

## Interactive Lifecycle Management

The console transforms sandbox orchestration into visual workflows through mutation handlers and state-aware UI components that handle error conditions gracefully.

### Sandbox Control Interface

Each sandbox row renders actionable controls via the `Row` component in [`web/src/pages/Sandboxes.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Sandboxes.tsx). These controls include **Play** icons for resuming paused instances, **Pause** icons for suspending active sandboxes, and **Trash2** icons for terminating resources. The `SandboxActionErrorBanner` component surfaces backend error messages directly within the interface, providing immediate feedback when lifecycle operations fail.

```typescript
// web/src/pages/Sandboxes.tsx – Action buttons
<Button size="icon" variant="ghost"
        title={t('actions.resume')} onClick={onResume}
        disabled={busy}>
  <Play size={14} />
</Button>
<Button size="icon" variant="ghost"
        title={t('actions.kill')} onClick={onKill}
        disabled={busy}>
  <Trash2 size={14} className="text-cube-err" />
</Button>

```

### Mutation Handling and Cache Invalidation

Lifecycle actions utilize `useMutation` hooks that automatically invalidate the sandbox query cache upon completion. When an operator triggers a resume action, the `resumeMut` mutation sends a POST request to `/cubeapi/sandboxes/:id/resume`, then triggers `qc.invalidateQueries({ queryKey: ['sandboxes'] })` to force an immediate UI refresh. This pattern ensures that state changes reflect instantly across all connected browser sessions.

```typescript
// web/src/pages/Sandboxes.tsx – Resume mutation
const resumeMut = useMutation({
  mutationFn: (id: string) => {
    setPendingId(id);
    return sandboxApi.resume(id);   // POST /cubeapi/sandboxes/:id/resume
  },
  onMutate: () => setActionError(null),
  onError: onLifecycleError,
  onSettled: () => {
    setPendingId(null);
    qc.invalidateQueries({ queryKey: ['sandboxes'] });
  },
});

```

## Key Implementation Files

Visual sandbox management in the CubeSandbox repository depends on the following core files:

- **[`web/vite.config.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/vite.config.ts)** – Defines the development server port (5173) and API proxy configuration to the CubeAPI backend.
- **[`web/src/pages/Sandboxes.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Sandboxes.tsx)** – Implements the main dashboard with filtering, search, and lifecycle action capabilities.
- **[`web/src/api/client.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/api/client.ts)** – Provides the typed HTTP client wrapper for all CubeAPI endpoints.
- **[`web/src/pages/SandboxNew.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/SandboxNew.tsx)** – Contains the sandbox creation interface for instantiating new environments from templates.
- **[`web/src/pages/SandboxDetail.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/SandboxDetail.tsx)** – Renders detailed views showing sandbox logs, resource consumption, and granular controls.

## Summary

- **The CubeSandbox web console** runs as a React application on port 5173, proxied to the CubeAPI backend for seamless development and deployment.
- **React-Query integration** enables automatic polling every 5 seconds, ensuring the visual interface displays real-time sandbox states without manual refresh.
- **Typed API abstraction** in [`client.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/client.ts) provides safe, predictable HTTP interactions for listing, pausing, resuming, and terminating sandboxes.
- **Mutation handlers** with cache invalidation guarantee that lifecycle actions appear immediately in the UI while the `SandboxActionErrorBanner` surfaces backend failures.
- **Modular page components** separate concerns between list management ([`Sandboxes.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/Sandboxes.tsx)), creation workflows ([`SandboxNew.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/SandboxNew.tsx)), and detailed inspection ([`SandboxDetail.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/SandboxDetail.tsx)).

## Frequently Asked Questions

### What port does the CubeSandbox web console use by default?

The development server runs on **port 5173** as configured in [`web/vite.config.ts`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/vite.config.ts). This Vite-based setup proxies API requests to the CubeAPI service running on port 3000, allowing operators to access the console at `http://localhost:5173` during development.

### How does the console keep sandbox data synchronized in real-time?

The interface uses **React-Query's `refetchInterval`** mechanism set to 5 seconds in the `useQuery` configuration within [`web/src/pages/Sandboxes.tsx`](https://github.com/TencentCloud/CubeSandbox/blob/main/web/src/pages/Sandboxes.tsx). This polls the `/cubeapi/sandboxes` endpoint continuously, automatically updating the React state and re-rendering the sandbox list whenever the backend state changes.

### Can I manage sandbox lifecycles directly from the web interface?

Yes. The console provides **visual lifecycle controls** including pause, resume, and kill actions accessible through icon buttons in each sandbox row. These trigger `useMutation` hooks that call the corresponding API methods (`sandboxApi.pause`, `sandboxApi.resume`, `sandboxApi.kill`) and automatically refresh the data upon completion.

### What happens if a lifecycle action fails in the web console?

Failed mutations trigger the **onError** callback in the mutation configuration, which updates local React state to display the error message through the `SandboxActionErrorBanner` component. This provides immediate visual feedback within the interface without requiring operators to check server logs or terminal output.