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

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

// 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, while specialized views for creation (SandboxNew.tsx) and detailed inspection (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 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.

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

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

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

// 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 – Defines the development server port (5173) and API proxy configuration to the CubeAPI backend.
• web/src/pages/Sandboxes.tsx – Implements the main dashboard with filtering, search, and lifecycle action capabilities.
• web/src/api/client.ts – Provides the typed HTTP client wrapper for all CubeAPI endpoints.
• web/src/pages/SandboxNew.tsx – Contains the sandbox creation interface for instantiating new environments from templates.
• 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 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), creation workflows (SandboxNew.tsx), and detailed inspection (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. 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. 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.

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