Try it before connecting Claude

npx claude-webdesk demo
# or: uvx claude-webdesk demo

Open the login link printed in your terminal. The demo uses a separate temporary workspace, synthetic sessions and simulated output. No Claude installation, API key, or model calls. Uploads and task records stay in that temporary directory; its path is printed for cleanup. Node.js 22+ is required with either installation method.

Why a webdesk?

Your agent is running on a VPS. Your screenshot is on your laptop. Yesterday's conversation is buried in terminal history. The generated report is still on the server.

Claude Webdesk brings that workflow into one authenticated, self-hosted page:

No hosted account. No database. No frontend CDN. The Node server has no production npm dependencies; browser libraries ship bundled. The full history plugin uses Python's standard library. The initial interface is primarily Chinese; documentation is available in English and Chinese.

Quick start

On the machine where Claude Code is installed and authenticated:

npx claude-webdesk --cwd /absolute/path/to/project

Default address: http://127.0.0.1:8090. A random access token and a login link are printed on startup. Use an SSH tunnel from your laptop when running on a remote server:

ssh -N -L 8090:127.0.0.1:8090 user@your-server

Open http://127.0.0.1:8090 locally and enter the token. To keep a stable access token across restarts:

export CLAUDE_WEBDESK_TOKEN="$(openssl rand -hex 32)"
npx claude-webdesk --cwd /srv/my-project

Requirements: Node.js 22+, Linux/macOS, installed and authenticated Claude Code. Full session management additionally requires Python 3.10+. CLI flags were checked against Claude Code 2.1.296; run claude-webdesk doctor to detect missing capabilities on other versions. Linux is the tested platform; macOS process handling and Windows are not verified. The desktop and 390px mobile browser flows are tested with Chromium.

Install permanently

npm install -g claude-webdesk
claude-webdesk doctor
claude-webdesk --cwd /srv/my-project

# Python/uv distribution (still requires Node.js 22+)
uv tool install claude-webdesk
# or: pip install claude-webdesk

Choose one installation channel. The Python package includes the same built Node app; it does not download npm packages at startup or install Claude Code for you.

Continue a conversation

Open CLI sessions in the sidebar or the full session manager. Choose a conversation, enter your next instruction and run. Check Fork session to preserve the original thread and explore a new direction. Resume uses the original project's directory; that directory must still exist and be inside --workspace-root, if configured.

Permissions and spending

• Plan is the default Claude permission mode for planning and analysis.
• Accept edits lets Claude approve file edits. Commands still follow its permission rules.
• Don't ask uses only already-allowed tools.

Webdesk passes --permission-prompts none: actions requiring an unanswered approval are denied, and returned permission denials appear in the result. There is no permission-bypass switch or interactive approval UI. These modes are not an operating-system sandbox. Existing Claude settings, hooks and tools run as your OS user. Use trusted projects and plugins; isolate the service at the OS/container level when needed.

The budget input maps to Claude's --max-budget-usd; enforcement and reporting belong to the CLI. Cost estimates are CLI-reported API values, not your subscription invoice. Failed/unsupported runs may have no usage metrics.

Configuration

Run claude-webdesk --help for all flags; see config.example.json.

Precedence: CLI flags > CLAUDE_WEBDESK_TOKEN > JSON configuration > defaults. Additional flags include --token (16+ characters) and --disable-plugins. Use environment/config for persistent tokens rather than command-line arguments. Changing the task directory does not change the file browser's root. Uploads go into webdesk-uploads/ within that root and have unique names; each file is limited to 25 MiB. Dotfiles, private key extensions, symlinks and dependency folders are excluded from sharing. Downloads are attachments. For large directory transfers and resumable downloads, use remote-fileshare.

Self-hosting and boundaries

Use an SSH tunnel or an HTTPS reverse proxy. Deployment examples include Caddy and a user systemd service. This is a single-user workbench, not a multi-tenant service. A holder of its token can launch Claude tasks and access project files and conversation history. Login cookies are HttpOnly/SameSite=Strict; cross-origin requests are rejected and failed logins are rate-limited. Login links use a URL fragment so the token is not sent in HTTP query logs.

One task runs at a time. Closing a browser tab keeps it running; stopping the server interrupts it. Tasks do not automatically restart. Web logs have per-task retention caps (4M raw characters, 2M answer characters, 8 MB/20,000 events), but total stored history is not automatically pruned. Native session scans are not indexed yet. Raw output can include tool results; protect exports as private data.

Develop

git clone https://github.com/chao5go/claude-webdesk.git
cd claude-webdesk
npm ci
npm run build
npm run demo

npm run check
npm test
npm run test:python
npx playwright install chromium
npm run test:browser
npm run test:package

Tests use isolated fixtures and simulated Claude output, never your private transcripts or paid models. Automated tests do not establish real-model compatibility beyond checked CLI flags. Architecture · Release process · Roadmap

Built from practical tools

This project builds on codex-webdesk's authenticated task/plugin architecture and the author's local Claude history viewer. remote-fileshare inspired the screenshot-to-agent and artifact-download workflow. They remain useful standalone tools.

If this saves you a trip back to SSH, a star helps other developers find it. Useful bug reports and real workflow examples help even more. See CONTRIBUTING.md.

MIT licensed. Independent community project, not affiliated with or endorsed by Anthropic. Claude and Claude Code are Anthropic trademarks. CLI integration: official reference and programmatic use.