CloudCLI (Claude Code UI) Deployment & Usage Guide

Prerequisites

• Node.js v22 or higher
• Package Manager: npm (included with Node.js)
• CLI Tools (at least one required):
  • Claude Code CLI installed and authenticated, or
  • Cursor CLI installed and authenticated, or
  • Codex CLI installed and authenticated
• Git (for cloning repository or Git Explorer functionality)
• PM2 (optional, for production background service deployment)

Installation

Method 1: One-time Execution (No Install)

npx @siteboon/claude-code-ui

Server starts at http://localhost:3001. Stop with Ctrl+C, restart by running the command again.

Method 2: Global Installation (Recommended)

npm install -g @siteboon/claude-code-ui

Start anytime with:

claude-code-ui
# or
cloudcli

Update to latest version:

cloudcli update

Method 3: Local Development

git clone https://github.com/siteboon/claudecodeui.git
cd claudecodeui
npm install
cp .env.example .env

Configuration

Environment Variables

Edit .env file (copied from .env.example):

CLI Tool Configuration

Cursor CLI: Config stored at ~/.cursor/cli-config.json (auto-created if missing).

Security: All Claude Code tools are disabled by default. After first launch:

1. Open the web interface
2. Click the gear icon in sidebar
3. Enable required tools selectively
4. Apply settings

External API Access (Self-hosted)

For API access to the agent endpoints:

1. Generate API keys in the web UI
2. Include in requests: X-API-Key header or apiKey query parameter
3. In Platform mode (IS_PLATFORM=true), authentication is handled externally and the default user context is used automatically

Build & Run

Development Mode (Hot Reload)

npm run dev

Access at http://localhost:3001 (or configured PORT).

Production Mode

npm start

CLI Options

cloudcli --port 8080                    # Custom port
cloudcli --database-path /path/to/data    # Custom data directory
cloudcli status                          # Show configuration and data locations
cloudcli version                       # Show version info
cloudcli help                          # Show all options

Background Service (Production)

Install PM2:

npm install -g pm2

Start as background service:

pm2 start cloudcli --name "claude-code-ui"
pm2 start cloudcli --name "claude-code-ui" -- --port 8080

Auto-start on system boot:

pm2 startup
pm2 save

Stop service:

pm2 stop claude-code-ui

Deployment

Self-Hosted (Recommended)

Use PM2 configuration above for persistent local or server deployment. Suitable for:

• Personal remote access (mobile/desktop)
• Team internal tools
• Home server setups

Managed/Platform Deployment

Set IS_PLATFORM=true environment variable when deploying to:

• Railway
• Render
• Heroku
• AWS/GCP/Azure (behind authentication proxy)

This mode disables local API key validation and assumes external authentication.

Docker (Manual)

While no official Docker image is provided, you can containerize:

FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install --production
COPY . .
EXPOSE 3001
CMD ["npm", "start"]

Expose port 3001 (or configured PORT) and mount a volume for persistent database storage.

Troubleshooting

Port Already in Use

# Find process using port 3001
lsof -i :3001
# Kill process or use different port
cloudcli --port 8080

CLI Tools Not Detected

• Ensure claude, cursor, or codex commands are available in system PATH
• Verify CLI tools are authenticated (run them standalone first)
• Check that Node.js version is v22 or higher: node --version

Tools Disabled / Operations Blocked

By default, all tools are disabled for security. You must manually enable them:

1. Open web interface
2. Navigate to Tools Settings (gear icon)
3. Enable specific tools (File Write, Bash, etc.)
4. Restart session if needed

Authentication Failures (API Access)

• 401 Errors: Include valid API key in X-API-Key header
• Platform mode: Ensure IS_PLATFORM=true is set if running behind auth proxy
• Check cloudcli status to verify database and config paths

Database Permission Errors

If using custom database path:

# Ensure directory exists and is writable
mkdir -p /path/to/data
chmod 755 /path/to/data
cloudcli --database-path /path/to/data

Git Operations Failing

• Verify Git is installed: git --version
• Ensure repository permissions (SSH keys or HTTPS credentials configured)
• Check project path encoding (dashes vs slashes in project names)