From e07beeb7d494a02747565c3b52c0819037199d65 Mon Sep 17 00:00:00 2001 From: amacsmith Date: Mon, 12 Jan 2026 18:42:08 -0500 Subject: [PATCH 1/3] docs: add authentication section to README Adds documentation explaining the built-in authentication system: - First-time setup process - Single-user system design - JWT-based auth with bcrypt - Security recommendations for VPS/remote deployment - HTTPS and firewall guidance Fixes #291 Co-Authored-By: Claude Opus 4.5 --- README.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/README.md b/README.md index b01ce3562..e9a5e3960 100644 --- a/README.md +++ b/README.md @@ -184,6 +184,24 @@ The application will start at the port you specified in your .env ## Security & Tools Configuration +### Authentication + +Claude Code UI includes **built-in authentication** to protect your data when running on a server or VPS: + +- **First-time setup**: When you first access the UI, you'll be prompted to create an admin account +- **Single-user system**: Only one user account is supported (designed for personal use) +- **JWT-based auth**: Secure token-based authentication with bcrypt password hashing +- **Session persistence**: Stay logged in across browser sessions + +> ⚠️ **Important for Remote/VPS Deployment**: If you're running Claude Code UI on a remote server or VPS, authentication is **essential** to prevent unauthorized access to your projects and Claude sessions. Make sure to: +> 1. Set a strong password during initial setup +> 2. Use HTTPS (via reverse proxy like nginx/caddy) for production deployments +> 3. Consider firewall rules to restrict access to trusted IPs + +For local-only use (localhost), the authentication still applies but the security risk is lower since access is limited to your machine. + +### Tool Permissions + **🔒 Important Notice**: All Claude Code tools are **disabled by default**. This prevents potentially harmful operations from running automatically. ### Enabling Tools From 1b55b5adbdf708b6c958393a31048587784817af Mon Sep 17 00:00:00 2001 From: amacsmith Date: Mon, 12 Jan 2026 19:10:31 -0500 Subject: [PATCH 2/3] fix: correct numbered list sequence in Enabling Tools section Changes step numbers from 1, 3, 4 to 1, 2, 3 for proper sequential ordering. Co-Authored-By: Claude Opus 4.5 --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index e9a5e3960..ad86d15d8 100644 --- a/README.md +++ b/README.md @@ -209,8 +209,8 @@ For local-only use (localhost), the authentication still applies but the securit To use Claude Code's full functionality, you'll need to manually enable tools: 1. **Open Tools Settings** - Click the gear icon in the sidebar -3. **Enable Selectively** - Turn on only the tools you need -4. **Apply Settings** - Your preferences are saved locally +2. **Enable Selectively** - Turn on only the tools you need +3. **Apply Settings** - Your preferences are saved locally
From f7bd805ab23011d62247b0ae568f6b05a60fa968 Mon Sep 17 00:00:00 2001 From: amacsmith Date: Tue, 13 Jan 2026 22:08:30 -0500 Subject: [PATCH 3/3] docs: add session management and password recovery documentation - Add specific password requirements (12+ chars recommended) - Add rate limiting recommendation for VPS deployments - Document JWT token storage (localStorage) and expiry behavior - Add password recovery instructions (database reset) - Note that reset clears saved settings and GitHub tokens Addresses CodeRabbit review feedback. Co-Authored-By: Claude Opus 4.5 --- README.md | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index ad86d15d8..2b149fe6c 100644 --- a/README.md +++ b/README.md @@ -194,12 +194,30 @@ Claude Code UI includes **built-in authentication** to protect your data when ru - **Session persistence**: Stay logged in across browser sessions > ⚠️ **Important for Remote/VPS Deployment**: If you're running Claude Code UI on a remote server or VPS, authentication is **essential** to prevent unauthorized access to your projects and Claude sessions. Make sure to: -> 1. Set a strong password during initial setup +> 1. Set a strong password during initial setup (minimum 12 characters recommended, with a mix of uppercase, lowercase, numbers, and symbols) > 2. Use HTTPS (via reverse proxy like nginx/caddy) for production deployments > 3. Consider firewall rules to restrict access to trusted IPs +> 4. Use a reverse proxy with rate limiting to protect against brute-force attacks For local-only use (localhost), the authentication still applies but the security risk is lower since access is limited to your machine. +#### Session Management + +- **Token storage**: JWT tokens are stored in your browser's localStorage +- **Token expiry**: Tokens do not expire by default - you stay logged in until you manually log out +- **Logging out**: Click the logout button to clear your session token + +#### Password Recovery + +If you forget your password, you'll need to reset the database: + +1. Stop the server +2. Delete the database file (default: `~/.claude-code-ui/database.sqlite` or the path in `DATABASE_PATH` env var) +3. Restart the server +4. Create a new admin account on first access + +> **Note**: This will also clear any saved settings and GitHub tokens. + ### Tool Permissions **🔒 Important Notice**: All Claude Code tools are **disabled by default**. This prevents potentially harmful operations from running automatically.