# Panel

Panel is the Nexuma web interface for operators and users. Operators manage the platform from one place. Users manage their own subscriptions, public links, configs, traffic, finance history, and account settings.

This page is public operator documentation. It describes panel capabilities, routes, API behavior, environment variables, and Docker deployment without requiring source-code access.

## Capabilities

### Admin Dashboard

- Node status grid.
- Recent audit log feed.
- Auto-refresh for operational visibility.

### Users

- User list with search and status filters.
- Approval, rejection, restore, block, edit, and delete actions.
- User profile details.
- User subscriptions.
- User subscription links.
- User node/protocol access matrix.
- User finance and balance transaction history.

### Tariffs

- Create, edit, and delete tariffs.
- Configure price, duration, traffic limit, active state, and allowed protocols.
- Restrict tariffs to selected nodes.
- Attach external subscription sources.
- Allow or block selected routing categories through tariff permissions.

### Subscriptions

- Create and cancel subscriptions.
- Filter subscriptions by status, user, and tariff.
- Toggle auto-renew.
- Create, rename, disable, reset, and delete public links.
- Restrict public links to selected nodes.

### Nodes

- List, create, edit, and delete nodes.
- Generate registration codes.
- Rotate node auth keys.
- Force config sync.
- Manage protocols.
- Manage outbounds for proxy chains.
- Manage routing config and apply routing templates.
- Manage masking sites.
- Install and restart Xray and MTProto.
- Update GeoIP/geosite files.
- Generate X25519 and ML-DSA-65 keys.
- View live runtime status and resource usage.

### Routing Rules

- Create, edit, and delete reusable rule sets.
- Manage custom rules and balancers.
- Assign routing configuration to nodes.

### External Subscriptions

- Create, edit, and delete external subscription sources.
- Test a source URL before attaching it to tariffs.
- Attach sources to tariffs so their share links are appended to subscriptions.

### Logs

- View audit events.
- Filter logs by action and user.

### Self-Service

- Personal dashboard.
- Traffic charts and hourly distribution.
- Personal subscriptions.
- Personal public links.
- Personal configs.
- Finance history and balance.
- Account profile settings.
- Telegram account linking and unlinking.

### Public Subscription Page

- Public `/sub/:uuid` page.
- Subscription metadata.
- Raw config download/copy.
- QR code.
- Per-config copy buttons.
- MTProto link display.

## Environment Variables

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `NUXT_PUBLIC_API_BASE` | No | `/api` | Browser-facing API base. Use `/api` for same-origin panel proxying. |
| `NUXT_CORE_URL` | Yes for Docker | `http://localhost:3000` fallback | Core URL used by the panel server proxy. |

Recommended production values:

```env
NUXT_PUBLIC_API_BASE=/api
NUXT_CORE_URL=http://core:3000
```

## Docker Compose

Panel-only deployment:

```yaml
version: '3.9'

services:
  panel:
    image: nexuma/panel:latest
    container_name: nexuma-panel
    restart: unless-stopped
    environment:
      NUXT_PUBLIC_API_BASE: /api
      NUXT_CORE_URL: https://core.example.com
    ports:
      - "3010:3000"
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:3000/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 30s
```

Run:

```bash
docker compose up -d
```

Open:

```text
http://your-server:3010
```

## Routes

Public routes:

| Route | Purpose |
| --- | --- |
| `/auth/login` | Login screen. |
| `/auth/pending` | Waiting-for-approval screen. |
| `/auth/telegram/redirect` | Telegram login callback. |
| `/auth/telegram/link-redirect` | Telegram account-link callback. |
| `/sub/:uuid` | Public subscription page. |
| `/:uuid` | Root UUID entry point for clients and redirects. |

Admin routes:

| Route | Purpose |
| --- | --- |
| `/` | Dashboard. |
| `/users` | User list. |
| `/users/:id` | User profile. |
| `/users/:id/subscriptions` | User subscriptions. |
| `/users/:id/links` | User links. |
| `/users/:id/access` | User node/protocol access. |
| `/users/:id/finance` | User finance. |
| `/tariffs` | Tariff management. |
| `/nodes` | Node list. |
| `/nodes/:id` | Node overview. |
| `/nodes/:id/protocols` | Node protocols. |
| `/nodes/:id/outbounds` | Node outbounds. |
| `/nodes/:id/routing` | Node routing. |
| `/nodes/:id/masking` | Node masking site. |
| `/subscriptions` | Subscription management. |
| `/routing-rules` | Routing rule set management. |
| `/external-subscriptions` | External source management. |
| `/logs` | Audit logs. |
| `/config-builder` | Protocol config builder. |

User routes:

| Route | Purpose |
| --- | --- |
| `/me` | Personal dashboard. |
| `/me/subscriptions` | Personal subscriptions. |
| `/me/configs` | Personal configs. |
| `/me/links` | Personal links. |
| `/me/finance` | Personal finance history. |

## API Behavior

- Browser API calls use `NUXT_PUBLIC_API_BASE`.
- The recommended browser base is `/api`.
- Requests to `/api/*` are proxied by the panel server to `NUXT_CORE_URL`.
- The proxy strips the `/api` prefix before forwarding.
- UUID root requests from VPN clients are proxied to Core subscription output when the request does not ask for HTML.
- Access and refresh tokens are stored in the browser.
- API calls include the bearer access token when available.
- A `401` response triggers a refresh attempt and one retry.
- Failed operations are shown as user-facing notifications unless marked silent.

## Auth Rules

- `/auth/*`, `/sub/*`, and UUID-only root paths are public.
- Pending users can only see the pending page and logout.
- Admin pages require an admin account.
- Self-service pages require a logged-in user.

## Typical Operator Flow

1. Log in as admin.
2. Create or approve users.
3. Create tariffs.
4. Add or register nodes.
5. Configure node protocols.
6. Create subscriptions.
7. Share public subscription links.
8. Monitor node status, usage, and logs.

## Public Subscription Flow

1. User or admin opens a public link.
2. The panel loads subscription metadata from Core.
3. The panel displays configs, QR, traffic, expiry, and MTProto links.
4. VPN clients can request the UUID directly and receive raw subscription output.