@codemantle/panel

CodeMantle control-plane service as an npm package.

It runs the WebSocket control channel, HTTP API, and UI used to orchestrate connected @codemantle/agent-daemon instances.

What this package includes

• Reverse WebSocket server for daemon tunnels.
• HTTP API for orchestration and policy-aware actions.
• Static web UI for device/session operations.
• First-run env bootstrap (.env init) and env diagnostics commands.

Install

Run directly with npx (recommended):

npx @codemantle/panel start

Or install globally:

npm install -g @codemantle/panel
codemantle-panel start

First run and env bootstrap

If no .env exists, codemantle-panel start launches an interactive setup in TTY mode and writes .env for future runs.

Explicit init:

codemantle-panel init --env-file /opt/codemantle/.env

Headless init:

codemantle-panel init --non-interactive --env-file /opt/codemantle/.env \
  --set [email protected] \
  --set AUTH_OWNER_PASSWORD="replace-me" \
  --set VALID_TOKENS="replace-with-secure-token"

Notes:

• AUTH_OWNER_PASSWORD is converted to AUTH_OWNER_PASSWORD_HASH on generation.
• Generated files are written with restrictive permissions where supported.
• .env is appended to local .gitignore when missing.

CLI reference

codemantle-panel [start] [--env-file <path>] [--config-dir <dir>] [--non-interactive]
codemantle-panel init [--env-file <path>] [--config-dir <dir>] [--set KEY=VALUE] [--yes] [--force]
codemantle-panel migrate-env [--env-file <path>] [--write]
codemantle-panel doctor [--env-file <path>]

MFA setup

When MFA is enabled during interactive setup (codemantle-panel init or first-run), the CLI walks through the full configuration:

1. Provider selection — choose between totp (Google Authenticator, 1Password, Bitwarden, etc.) or authy.
2. Setup instructions — the generated TOTP secret is displayed as both a manual entry key and an otpauth:// URI that can be pasted into any authenticator app or used to generate a QR code.
3. Confirmation gate — setup pauses until you press Enter, so the secret is not accidentally scrolled past.

Example output:

Enable MFA (Y/n): y
MFA provider (TOTP/authy): totp

=== MFA Setup Instructions ===

Provider: TOTP (Google Authenticator, 1Password, Bitwarden, etc.)

Add this account to your authenticator app using one of the methods below:

  Manual entry key:
    JBSWY3DPEHPK3PXP...

  Or use this otpauth URI (paste into your app or generate a QR code):
    otpauth://totp/CodeMantle:owner%40example.com?secret=JBSWY3DP...&issuer=CodeMantle&digits=6&period=30

  Account: [email protected]
  Type: TOTP | Digits: 6 | Period: 30s

Save this secret in a secure location. You will need it to log in.
===============================

Press Enter once you have saved your MFA secret...

For headless/non-interactive init, pass the secret directly:

codemantle-panel init --non-interactive \
  --set AUTH_MFA_ENABLED=true \
  --set AUTH_MFA_PROVIDER=totp \
  --set AUTH_OWNER_2FA_PASSKEY="YOUR_BASE32_SECRET"

Required and recommended environment variables

Required:

• VALID_TOKENS (comma-separated daemon auth tokens)
• JIT_CREDENTIAL_SIGNING_KEY
• AUTH_OWNER_EMAIL
• AUTH_OWNER_PASSWORD_HASH (or AUTH_OWNER_PASSWORD)

Core runtime:

• CONTROL_PLANE_PORT (default 8787)
• CONTROL_PLANE_API_PORT (default 8788)
• HEARTBEAT_SECONDS
• REQUEST_TIMEOUT_MS
• MAX_API_BODY_BYTES
• MAX_PROMPT_CHARS

Auth and session security:

• AUTH_MODE (local, disabled, oidc stub)
• AUTH_MFA_ENABLED
• AUTH_MFA_PROVIDER (authy or totp, RFC6238)
• AUTH_MFA_REQUIRE_FOR_ALL_USERS
• AUTH_OWNER_2FA_PASSKEY (recommended)
• AUTH_OWNER_TOTP_SECRET (legacy alias)
• AUTH_COOKIE_SECURE (set true for TLS/internet deployments)
• AUTH_SESSION_COOKIE_NAME
• AUTH_CSRF_COOKIE_NAME

Schema/versioning:

• PANEL_ENV_SCHEMA_VERSION (managed by init/migrate tooling)

See .env.example for defaults and formatting.

24/7 operation

PM2 baseline:

pm2 start "npx @codemantle/panel start --env-file /opt/codemantle/.env --non-interactive" --name codemantle-panel
pm2 save
pm2 startup

systemd baseline:

[Unit]
Description=CodeMantle Panel
After=network.target

[Service]
Type=simple
WorkingDirectory=/opt/codemantle
EnvironmentFile=/opt/codemantle/.env
ExecStart=/usr/bin/env npx @codemantle/panel start --env-file /opt/codemantle/.env --non-interactive
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Reverse proxy

For production deployments, place the panel behind a reverse proxy with TLS termination.

location /ws {
    proxy_pass http://127.0.0.1:8787;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location /ws-ui {
    proxy_pass http://127.0.0.1:8788;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

location / {
    proxy_pass http://127.0.0.1:8788;
}

Notes:

• Set AUTH_COOKIE_SECURE=true in your .env when using TLS.
• Agent daemons connect via CONTROL_PLANE_URL=wss://codemantle.example.com/ws.

For the full guide with Certbot TLS setup, HTTP→HTTPS redirect, and systemd service management, see the Deployment guide.

Validation and upgrades

Check env health:

codemantle-panel doctor --env-file /opt/codemantle/.env

Preview env migration output:

codemantle-panel migrate-env --env-file /opt/codemantle/.env

Apply migration in place:

codemantle-panel migrate-env --env-file /opt/codemantle/.env --write

Development

npm ci
npm run dev

Build and run built output:

npm run build
npm run start

Security and compatibility

• Protocol contract remains additive-first (v=1).
• Daemon trust boundaries (path/process guardrails) remain daemon-enforced.
• For production, run behind TLS/reverse proxy and keep AUTH_COOKIE_SECURE=true.

For full architecture and security details, see:

• https://github.com/XQuestCode/codemantle/blob/main/docs/architecture.md
• https://github.com/XQuestCode/codemantle/blob/main/docs/protocol.md
• https://github.com/XQuestCode/codemantle/blob/main/docs/security-model.md