a744080e65
## Skills Library - Browse and install 36+ community skills from Anthropic & Superpowers - Local skill templates (Rails, React, testing) - Create custom project-specific skills - Beautiful UI with search and filtering - /claude-os-skills command for CLI management ## Session Insights - Parse Claude Code native .jsonl session files - Extract patterns, decisions, blockers automatically - Track tool usage and file changes - Session summary generation for LLM processing ## Documentation - Updated README with v2.3 features - Updated API_REFERENCE with new endpoints - Added SKILLS_GUIDE.md and SESSIONS_GUIDE.md - Updated GitHub Pages (docs/index.html) - Reorganized docs (internal_docs for private) ## Bug Fixes - Fixed httpx client closure in community skill install - Fixed frontend request format for skill install 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
190 lines
4.7 KiB
Markdown
190 lines
4.7 KiB
Markdown
# Claude OS Authentication Setup
|
|
|
|
Simple email/password authentication to keep strangers out of your Claude OS frontend.
|
|
|
|
## Features
|
|
|
|
✅ **Optional Authentication** - Disabled by default, enable when needed
|
|
✅ **Environment-based** - No database required for user management
|
|
✅ **JWT Tokens** - 7-day token expiration
|
|
✅ **Secure** - Bcrypt password hashing
|
|
✅ **Simple** - Single user account via environment variables
|
|
|
|
## Quick Start
|
|
|
|
### 1. Enable Authentication
|
|
|
|
Set environment variables in your `.env` file or server environment:
|
|
|
|
```bash
|
|
# Required: Email for login
|
|
CLAUDE_OS_EMAIL=admin@example.com
|
|
|
|
# Option 1: Plain password (development only - will be hashed automatically)
|
|
CLAUDE_OS_PASSWORD=your_secure_password_here
|
|
|
|
# Option 2: Pre-hashed password (recommended for production)
|
|
CLAUDE_OS_PASSWORD_HASH=$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5hhA82jdg8jpu
|
|
|
|
# Optional: Custom secret key for JWT (auto-generated if not set)
|
|
CLAUDE_OS_SECRET_KEY=your-super-secret-key-min-32-chars
|
|
```
|
|
|
|
### 2. Generate Password Hash (Production)
|
|
|
|
For production, use a pre-hashed password instead of plain text:
|
|
|
|
```bash
|
|
# Install dependencies first
|
|
cd ~/Projects/claude-os
|
|
source venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
# Generate hash
|
|
python3 -c "from passlib.context import CryptContext; print(CryptContext(schemes=['bcrypt']).hash('your_password_here'))"
|
|
```
|
|
|
|
Copy the output and use it as `CLAUDE_OS_PASSWORD_HASH` in your `.env` file.
|
|
|
|
### 3. Restart Claude OS
|
|
|
|
```bash
|
|
# Local (Mac)
|
|
./stop.sh
|
|
./start.sh
|
|
|
|
# Production Server
|
|
sudo systemctl restart claude-os
|
|
```
|
|
|
|
### 4. Login
|
|
|
|
Visit your Claude OS frontend:
|
|
- Local: http://localhost:5173/login
|
|
- Production: https://your-domain.com/login
|
|
|
|
Use the email and password you configured.
|
|
|
|
## Production Deployment
|
|
|
|
### Server Environment Variables
|
|
|
|
Add to `/opt/claude-os/.env`:
|
|
|
|
```bash
|
|
CLAUDE_OS_EMAIL=admin@pistn.com
|
|
CLAUDE_OS_PASSWORD_HASH=$2b$12$xyz... # Generated hash
|
|
CLAUDE_OS_SECRET_KEY=your-32-char-secret
|
|
```
|
|
|
|
Restart the service:
|
|
|
|
```bash
|
|
sudo systemctl restart claude-os
|
|
```
|
|
|
|
## Disable Authentication
|
|
|
|
To disable authentication (open access):
|
|
|
|
```bash
|
|
# Remove or comment out these variables in .env:
|
|
# CLAUDE_OS_EMAIL=...
|
|
# CLAUDE_OS_PASSWORD=...
|
|
# CLAUDE_OS_PASSWORD_HASH=...
|
|
```
|
|
|
|
Restart Claude OS. The frontend will allow access without login.
|
|
|
|
## How It Works
|
|
|
|
### Backend (FastAPI)
|
|
|
|
- **`/api/auth/login`** - Login endpoint, returns JWT token
|
|
- **`/api/auth/me`** - Get current user info
|
|
- **`/api/auth/status`** - Check if authentication is enabled
|
|
|
|
### Frontend (React)
|
|
|
|
- **Login Page** - Beautiful gradient login form
|
|
- **Auth Context** - Manages authentication state
|
|
- **Protected Routes** - Automatically redirects to login if not authenticated
|
|
- **Token Storage** - JWT stored in localStorage (7-day expiration)
|
|
|
|
### Security Features
|
|
|
|
✅ **Bcrypt hashing** - Industry-standard password encryption
|
|
✅ **JWT tokens** - Stateless authentication
|
|
✅ **Automatic expiration** - Tokens expire after 7 days
|
|
✅ **HTTPS recommended** - Use SSL in production
|
|
✅ **No database needed** - Single user, environment-based
|
|
|
|
## Troubleshooting
|
|
|
|
### "Authentication is not configured"
|
|
|
|
You haven't set the `CLAUDE_OS_EMAIL` environment variable. Set it and restart.
|
|
|
|
### "Incorrect email or password"
|
|
|
|
Check your `.env` file:
|
|
- Email matches exactly (case-sensitive)
|
|
- If using `CLAUDE_OS_PASSWORD`, make sure it's correct
|
|
- If using `CLAUDE_OS_PASSWORD_HASH`, regenerate the hash
|
|
|
|
### Login page doesn't appear
|
|
|
|
Make sure your Claude OS frontend is running:
|
|
|
|
```bash
|
|
# Local development
|
|
cd frontend
|
|
npm run dev
|
|
|
|
# Production (should be served by Nginx)
|
|
curl http://localhost:5173
|
|
```
|
|
|
|
### Token expired
|
|
|
|
Tokens last 7 days. Just login again to get a new token.
|
|
|
|
## Multiple Users
|
|
|
|
This system is designed for single-user access. For multiple users:
|
|
|
|
1. **Simple approach**: Share one account with your team
|
|
2. **Advanced approach**: Extend the auth system to use a database (requires custom implementation)
|
|
|
|
For most teams deploying Claude OS internally, a single shared account is sufficient since it's:
|
|
- Behind your firewall
|
|
- For trusted team members only
|
|
- Just to keep strangers out (not enterprise-grade auth)
|
|
|
|
## Security Best Practices
|
|
|
|
### Development (Local)
|
|
|
|
```bash
|
|
CLAUDE_OS_EMAIL=dev@localhost
|
|
CLAUDE_OS_PASSWORD=dev123
|
|
```
|
|
|
|
Fine for local development. Password is hashed automatically.
|
|
|
|
### Production (Server)
|
|
|
|
```bash
|
|
CLAUDE_OS_EMAIL=admin@yourcompany.com
|
|
CLAUDE_OS_PASSWORD_HASH=$2b$12$xyz... # Pre-hashed
|
|
CLAUDE_OS_SECRET_KEY=randomly-generated-32-char-secret
|
|
```
|
|
|
|
✅ **Use hashed passwords**
|
|
✅ **Use strong secret keys**
|
|
✅ **Use HTTPS/SSL**
|
|
✅ **Rotate passwords periodically**
|
|
|
|
---
|
|
|
|
**Questions?** Check the main Claude OS README or open an issue on GitHub.
|