<!-- source: https://deepwiki.com/qhkm/zeptoclaw/12.4-panel-deployment -->

# Panel Deployment

- panel/.gitignore
- panel/README.md
- panel/eslint.config.js
- panel/index.html
- panel/package.json
- panel/pnpm-lock.yaml
- panel/src/App.tsx
- src/api/middleware.rs
- src/api/mod.rs
- src/api/openai_types.rs
- src/api/routes/mod.rs
- src/api/routes/openai.rs
- src/api/server.rs
- src/cli/panel.rs
- src/cli/serve.rs
- src/providers/plugin.rs
- src/providers/retry.rs
- src/providers/types.rs

## Purpose and Scope

This document covers the **Panel** — ZeptoClaw's web-based control panel for monitoring and managing agent instances. The panel consists of two primary components:

1. API Server — An Axum based REST API that also supports WebSocket event streaming and an OpenAI-compatible completion proxy.
2. Frontend — A modern React single-page application (SPA) built with Vite and Tailwind CSS.

The panel provides a graphical interface for viewing agent sessions, managing cron jobs and routines, monitoring health metrics, viewing logs, managing kanban tasks, and observing live agent activity.

**Sources:** [src/api/server.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L1-L12) [panel/package.json1-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/panel/package.json#L1-L37) [src/api/mod.rs1-12](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/mod.rs#L1-L12)

## System Architecture

The panel operates as an integrated HTTP server. The API server serves both REST endpoints and handles WebSocket upgrades. The frontend is a static React application typically served from a distribution directory.

### Component Overview

The following diagram illustrates the relationship between the Axum server state, the route handlers, and the underlying ZeptoClaw subsystems.

**Panel Architecture: Code Entity Map**

```

```

**Sources:** [src/api/server.rs14-54](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L14-L54) [src/api/server.rs92-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L92-L175) [src/api/routes/mod.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/routes/mod.rs#L1-L11)

## API Server Implementation

The API server is the backbone of the panel, managing authentication, data persistence, and real-time communication.

### AppState and Shared Resources

The `AppState` struct is the central container for shared resources. It is wrapped in an `Arc` and passed to every Axum route handler via the `State` extractor.

**Sources:** [src/api/server.rs16-54](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L16-L54) [src/api/server.rs58-76](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L58-L76)

### REST Route Modules

The server organizes functionality into discrete modules under `src/api/routes/`:

- auth : Handles login and JWT issuance src/api/routes/auth.rs
- sessions : CRUD operations for agent conversation history src/api/routes/sessions.rs
- channels : Surfaces health data for specific communication channels src/api/routes/channels.rs
- openai : Provides a proxy for OpenAI-compatible clients src/api/routes/openai.rs 29-82
- tasks : Backs the Kanban board with JSON persistence src/api/routes/tasks.rs
- ws : Manages WebSocket upgrades and event broadcasting src/api/routes/ws.rs
- cron / routines : Management endpoints for scheduled and event-driven tasks src/api/server.rs 137-163

**Sources:** [src/api/routes/mod.rs1-11](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/routes/mod.rs#L1-L11) [src/api/server.rs119-175](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L119-L175)

## Authentication and Security

ZeptoClaw implements a multi-layered security model for the API, combining static tokens, JWTs, and CSRF protection.

### Authentication Middleware

The `auth_middleware` in `src/api/middleware.rs` intercepts requests to enforce security policies.

1. Public Endpoints : /api/health , /api/csrf-token , and /api/auth/login bypass authentication src/api/middleware.rs 119-122
2. Token Validation : Accepts either the static api_token or a valid HS256 JWT in the Authorization: Bearer <token> header src/api/middleware.rs 134-143
3. CSRF Protection : Mutating requests ( POST , PUT , DELETE ) require a valid X-CSRF-Token header, except for OpenAI-compatible /v1/ routes which are intended for non-browser SDK use src/api/middleware.rs 145-165

### CSRF Mechanism

CSRF tokens are generated using HMAC-SHA256. They include a timestamp and are valid for 1 hour [src/api/middleware.rs67-69](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/middleware.rs#L67-L69) The `jwt_secret` (which rotates on server restart) is used as the HMAC key to ensure tokens cannot be reused across process lifetimes [src/api/middleware.rs32-33](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/middleware.rs#L32-L33)

**Sources:** [src/api/middleware.rs111-171](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/middleware.rs#L111-L171) [src/api/server.rs83-86](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L83-L86)

## OpenAI-Compatible API

ZeptoClaw can act as a drop-in replacement for OpenAI backends, allowing existing SDKs to target the ZeptoClaw gateway.

### Chat Completions

The `POST /v1/chat/completions` endpoint supports both standard JSON responses and Server-Sent Events (SSE) for streaming via the `LLMProvider::chat_stream` interface [src/api/routes/openai.rs109-129](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/routes/openai.rs#L109-L129)

**Data Flow: OpenAI Request to Provider**

```

```

**Sources:** [src/api/routes/openai.rs27-82](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/routes/openai.rs#L27-L82) [src/api/openai_types.rs18-39](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/openai_types.rs#L18-L39) [src/providers/types.rs83-100](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/providers/types.rs#L83-L100)

## Deployment and Installation

The panel is managed via the `zeptoclaw panel` CLI command, which handles asset resolution and server initialization.

### Panel CLI Commands

The `cmd_panel` function in `src/cli/panel.rs` manages the panel lifecycle:

- Install : zeptoclaw panel install [--download] builds the frontend from source or fetches pre-built assets src/cli/panel.rs 16-24
- Start : zeptoclaw panel (default) starts the Axum server. It resolves the static asset directory by checking ./panel/dist/ or ~/.zeptoclaw/panel/dist/ src/cli/panel.rs 73-85
- Auth : zeptoclaw panel auth reset-password allows managing credentials src/cli/panel.rs 35-46

### Token Management

The panel uses a persistent API token stored at `~/.zeptoclaw/panel.token` [src/cli/panel.rs107-111](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/panel.rs#L107-L111) If missing, `ensure_api_token()` generates a fresh 64-character hex token and saves it to disk [src/cli/panel.rs117-141](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/panel.rs#L117-L141)

**Sources:** [src/cli/panel.rs49-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/panel.rs#L49-L66) [src/cli/panel.rs144-183](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/cli/panel.rs#L144-L183)

## Frontend Application

The frontend is a React 19 application located in the `/panel` directory, using modern build tooling.

### Key Technologies

- Framework : React 19 with React Router 7 panel/package.json 16-18
- State Management : @tanstack/react-query for server state synchronization and caching panel/package.json 15
- Styling : Tailwind CSS 4 via Vite plugin panel/package.json 23-32
- Visualization : Recharts for displaying agent performance and token usage panel/package.json 19
- Interactivity : @dnd-kit for the Kanban board drag-and-drop functionality panel/package.json 13-14

### Build and Dev Scripts

- npm run dev : Starts the Vite development server panel/package.json 7
- npm run build : Compiles TypeScript ( tsc -b ) and generates the production bundle via Vite panel/package.json 8

**Sources:** [panel/package.json1-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/panel/package.json#L1-L37) [panel/pnpm-lock.yaml1-75](https://github.com/qhkm/zeptoclaw/blob/2c743d31/panel/pnpm-lock.yaml#L1-L75)

## WebSocket Events

Real-time updates (logs, status changes, tool execution) are pushed to the frontend via WebSockets.

### Event Distribution

When a WebSocket connection is established via `/ws/`, the server subscribes to the `EventBus` [src/api/server.rs20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L20-L20) To prevent resource exhaustion, a semaphore limits the number of active connections to `MAX_WS_CONNECTIONS` (5) [src/api/server.rs58-66](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L58-L66)

**Sources:** [src/api/server.rs19-20](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L19-L20) [src/api/server.rs32-37](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/server.rs#L32-L37) [src/api/routes/ws.rs](https://github.com/qhkm/zeptoclaw/blob/2c743d31/src/api/routes/ws.rs)
