Skip to content

docs: add authentication section to README #295

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
amacsmith wants to merge 6 commits into
base: main
Choose a base branch
from
Draft

docs: add authentication section to README #295

Changes from 5 commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
e07beeb
docs: add authentication section to README
Jan 12, 2026
1b55b5a
fix: correct numbered list sequence in Enabling Tools section
Jan 13, 2026
f7bd805
docs: add session management and password recovery documentation
Jan 14, 2026
29e9ff6
Merge branch 'main' into docs/add-authentication-note
amacsmith Jan 14, 2026
e0f2025
Merge branch 'main' into docs/add-authentication-note
amacsmith Jan 18, 2026
1d8ff55
Merge branch 'main' into docs/add-authentication-note
blackmammoth Feb 27, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 38 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -184,15 +184,51 @@ 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 (minimum 12 characters recommended, with a mix of uppercase, lowercase, numbers, and symbols)
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The recommendation to set a "minimum 12 characters" password is not enforced by the application. Based on the authentication implementation in server/routes/auth.js, there is no minimum password length validation. Consider either adding password validation to the backend or adjusting this documentation to note that this is a recommendation rather than an enforced requirement.

Suggested change
> 1. Set a strong password during initial setup (minimum 12 characters recommended, with a mix of uppercase, lowercase, numbers, and symbols)
> 1. Set a strong password during initial setup (use at least 12 characters with a mix of uppercase, lowercase, numbers, and symbols — this is a recommendation and is not enforced by the application)

Copilot uses AI. Check for mistakes.
> 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
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The statement "Tokens do not expire by default - you stay logged in until you manually log out" is accurate based on the JWT implementation (no expiry set in generateToken function). However, this is a security concern that should be documented differently. Consider rephrasing to acknowledge this as a potential security trade-off, for example: "Tokens do not expire by default for convenience, but this means you should log out when using shared or public computers."

Suggested change
- **Token expiry**: Tokens do not expire by default - you stay logged in until you manually log out
- **Token expiry**: Tokens do not expire by default for convenience; always log out when using shared or public computers to protect your account

Copilot uses AI. Check for mistakes.
- **Logging out**: Click the logout button to clear your session token

Comment on lines +210 to +212
Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This line implies token expiration is configurable (“do not expire by default”), but the implementation currently signs JWTs with no expiresIn at all (tokens never expire). Consider rewording to reflect the current behavior and to note the implication: a stolen token remains valid until logout/token removal or the server-side secret is rotated.

Suggested change
- **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
- **Token expiry**: Tokens currently have no automatic expiration; they remain valid as long as they exist in storage and the server's JWT secret is not rotated
- **Logging out**: Click the logout button to clear your session token from this browser
- **Security implication**: If someone gains access to your JWT (for example via a compromised device), they can use it until the token is removed (logout/clearing storage) or the server's JWT secret is rotated

Copilot uses AI. Check for mistakes.
#### 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.
Copy link

Copilot AI Jan 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The password recovery instructions state "This will also clear any saved settings and GitHub tokens." However, based on the codebase, tools settings, themes, and other preferences are stored in localStorage (browser-side), not in the SQLite database. Only the user account and potentially database-stored settings would be cleared. Consider clarifying that this only clears server-side data (user account) and that browser-stored settings (tools, preferences) will remain unless the browser cache is cleared separately.

Suggested change
> **Note**: This will also clear any saved settings and GitHub tokens.
> **Note**: Resetting the database clears all **server-side** data (your user account and any database-stored settings or GitHub tokens). **Client-side** settings stored in your browser (such as tool configuration, themes, and other preferences saved in localStorage) are not removed; clear your browser data separately if you want to reset those as well.

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Feb 27, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This note says resetting the DB clears “saved settings”, but most UI settings/tool permissions are stored in the browser’s localStorage, not in the SQLite DB. Resetting the DB will clear server-side stored credentials (e.g., GitHub tokens / API keys), but not local browser settings. Please adjust the wording to avoid confusing users about what is actually lost.

Suggested change
> **Note**: This will also clear any saved settings and GitHub tokens.
> **Note**: This will also clear any server-side stored credentials (e.g., GitHub tokens or API keys), but it will not reset UI preferences or tool permissions stored in your browser (localStorage).

Copilot uses AI. Check for mistakes.

### Tool Permissions

**🔒 Important Notice**: All Claude Code tools are **disabled by default**. This prevents potentially harmful operations from running automatically.

### Enabling Tools

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

<div align="center">

Expand Down