Skip to content
MZPanel MZPanel
ClaudeCode Run live Claude Code sessions on your own VPS — bring your own Claude subscription, chat, edit and operate the box.
CtrlK

ClaudeCode

ClaudeCode (/claudecode) runs live Claude Code sessions on a server you choose, streamed into a chat workspace in the panel. You bring your own Claude subscription (or an Anthropic-compatible API key); the sign-in and transcripts live on the VPS, and the AI operates the box through the same mz engine the rest of MZPanel drives. It needs the Pro plan or higher.

Start a session, step by step

Section titled “Start a session, step by step”
  1. Open ClaudeCode from the sidebar. Use the server switcher at the top of the left rail to pick an online server — offline and suspended servers are hidden.
  2. First time on this box? Open Connection & settings (the Capabilities button in the rail) and finish the Connection tab. The primary flow opens a link, you sign in on claude.com, and paste the short code back — the token stays on the VPS, the panel stores nothing. If Claude Code isn’t installed yet, the tab links you to install it as an extension.
  3. Once the box shows ready, click New to open a draft composer in a column.
  4. Pick your scope (the working directory), model and mode with the chips on the composer, type your first message, and send. Sending is what spawns the session — nothing starts on its own.
  5. Watch Claude think, run tools and edit files live. Dangerous edits pause for Approve / Deny unless you chose an auto-approving mode.

What else you can do

Section titled “What else you can do”

The workspace is a left rail (server switcher · session list · Connection & settings) plus a main area that can split into up to three columns, each a tab strip of sessions.

  • Resume a session — click any entry in the sidebar’s recent list; its transcript reloads from the box and reopens instantly.
  • Split & tab — set 1–3 columns, drag the divider to resize, and open a session in a split to run several at once (up to 16 live sessions per box).
  • Switch the working scope — the scope chip targets Root (whole-VPS admin under /root), a Project, a Site (its webroot), a Docker stack, or a linked server over SSH (see Fleet below).
  • Projects — New project scaffolds a /home/projects/<name> folder (code or website kind) that Claude works inside with its own CLAUDE.md and config.
  • Compose richly — attach an image, @-mention a file, run a /-command from .claude/commands, toggle extended thinking, or author a new slash command.
  • Code · Terminal · Preview · Config — side views on the focused session: a CodeMirror file browser, an embedded web terminal, a live-site iframe (website projects), and the project’s .claude config.
  • Changes — a git panel (status, per-file diff, revert/unstage, commit, history) for the focused project.
  • Connection & settings drawer tabs: Connection (sign-in lifecycle · sign out · safety & limits), Models (extra Anthropic-compatible providers), Fleet (hub-and-spoke over SSH), Activity (tool-call audit), and Maintenance (tiered cleanup + uninstall).
  • Delete / clear — remove a single session’s transcript, or clear ClaudeCode in tiers (caches · history · projects · sign-out).

How it works

Section titled “How it works”

ClaudeCode is a thin control layer over the real claude CLI running on your VPS:

  • Auth is on the box. Signing in drives claude auth login on the server; the credentials land in ~/.claude/.credentials.json and never touch the panel database. The Connection tab probes the agent (ai.auth) for installed / version / token / credentials and shows ready only when the CLI is installed and an auth source exists. You can optionally paste a setup-token that the box stores in a 0600 file.
  • Sessions stream over a one-time ticket. Opening a session mints a ticket (POST /v1/servers/:id/ai-sessions/ticket) gated by role (admin or operator), plan (Pro+) and the agent being online; the panel then upgrades to a WebSocket. On the box a small Node bridge drives @anthropic-ai/claude-agent-sdk, which is what enables per-tool Approve / Deny, model/mode hot-swap and streaming.
  • The AI’s toolset is mz + MCP. Inside a session Claude uses standard tools (Bash, Read/Edit, Grep…) plus a session-scoped MZPanel MCP server that exposes read tools from the control-plane inventory cache (sites, services, metrics, docs). Mutations flow through the same audited engine actions the dashboard uses.
  • State lives on the VPS. Transcripts are .jsonl files; projects live under /home/projects. The panel lists them (GET /v1/servers/:id/ai-sessions, /projects, /ai-sessions/:id/transcript) but is never the source of truth. Every tool call is recorded to the Activity audit.

CLI & automation

Section titled “CLI & automation”

ClaudeCode drives the on-box claude CLI, but the agent it becomes uses the mz CLI as its toolset — the same commands the dashboard dispatches. When you SSH into the box yourself, or when the on-box AI acts, both run mz directly:

Terminal window
mz site list --json                        # what the MCP read tools surface
mz service status --json                   # box services the AI can inspect

To understand or extend what the on-box AI can do, see The mz CLI and the command catalog. Fleet-level automation of ClaudeCode itself (minting tickets, listing sessions) is a control-plane concern — see the API reference (Max plan).

Gotchas & troubleshooting

Section titled “Gotchas & troubleshooting”
  • Pro plan or higher, on an online box. The ticket route refuses Free/Plus servers and offline agents. The server switcher only lists online, non-suspended servers.
  • Roles split by action. Any org admin or operator can run a session; only an owner/admin can manage the Claude sign-in, providers, and destructive Clear.
  • Claude Code must be installed first. It’s a separate on-box extension — the Connection tab links you to install it if the box reports it missing.
  • Sessions start only on an explicit click. New/resume spawn a session; nothing auto- opens (this is a deliberate guard). You can hold at most 16 live at once — past that you’ll see an inline “at capacity” hint until you close a tab.
  • bypassPermissions is still guarded. Even the “skip all permissions” mode can’t run a catastrophic op (rm -rf of root/home, mkfs, DROP DATABASE…) — a safety hook denies those in every mode.
  • 1M context = Opus only on a subscription. Opus runs at a native 1M window; Sonnet’s 1M is an API-tier beta that Pro/Max doesn’t grant, so the picker only offers Opus for 1M.
  • Fleet (hub-and-spoke) is early. Marking one box a hub to operate linked servers over SSH requires a WireGuard mesh and more than one server; treat it as a preview, and note that hard command policy over raw SSH isn’t enforceable — remote commands are visible in the transcript but not blocked.
  • Anthropic ToS. Using a personal Claude subscription token inside a commercial SaaS is restricted by Anthropic’s consumer terms; the self-login model (you auth your own tool on your own VPS, the panel holds nothing) is the low-risk path. For a fully compliant commercial setup, connect a per-user API key under the Models tab instead. Verify current terms for your case.
Section titled “Related”