# Installation and Startup of BitSeek Claw

This guide explains how to install and start BitSeek Claw (Hermes WebUI).

## System Requirements

- **Operating System**: macOS, Linux, or WSL2 (Windows requires WSL2)
- **Python**: 3.8 or higher
- **Hermes Agent**: Requires pre-installed Hermes Agent

## Installation Steps

### 1. Clone the Repository

```bash
git clone https://github.com/your-repo/agent-frontend-shell.git
cd agent-frontend-shell
```

### 2. Environment Configuration

#### Method 1: Using `.env` File (Recommended)

```bash
# Copy the example environment file
cp .env.example .env

# Edit the .env file to configure necessary parameters
nano .env
```

#### Method 2: Setting Environment Variables Directly

```bash
export HERMES_WEBUI_HOST=127.0.0.1
export HERMES_WEBUI_PORT=8787
export HERMES_HOME=~/.hermes
```

### 3. Starting the Service

#### Method 1: Using Startup Script (Recommended)

```bash
# Start using start.sh
./start.sh
```

#### Method 2: Using Python Launcher

```bash
# Start using bootstrap.py (automatically checks dependencies)
python3 bootstrap.py
```

#### Method 3: Using Control Script

```bash
# Manage service using ctl.sh
./ctl.sh start
```

## Startup Parameters

### Environment Variable Configuration

| Variable Name | Default Value | Description |
|---------------|---------------|-------------|
| `HERMES_WEBUI_HOST` | `127.0.0.1` | Listening address |
| `HERMES_WEBUI_PORT` | `8787` | Listening port |
| `HERMES_HOME` | `~/.hermes` | Hermes main directory |
| `HERMES_WEBUI_STATE_DIR` | - | State directory path |
| `HERMES_WEBUI_DEFAULT_WORKSPACE` | - | Default workspace path |

### Startup Options

```bash
# Start with specific port
HERMES_WEBUI_PORT=8888 ./start.sh

# Start with specific host and port
HERMES_WEBUI_HOST=0.0.0.0 HERMES_WEBUI_PORT=8787 ./start.sh

# Start with custom state directory
HERMES_WEBUI_STATE_DIR=/tmp/hermes-state ./start.sh
```

## Accessing the Interface

After successful startup, access in your browser:

```
http://localhost:8787
```

### First-time Access

1. Open your browser and navigate to the above address
2. First-time access will enter the **First Run Wizard**
3. Follow the wizard prompts to configure:
   - AI provider settings (e.g., OpenAI, Anthropic, etc.)
   - API key configuration
   - Basic preference settings

## Docker Deployment

### Single Container Deployment

```bash
# Using Docker Compose
docker-compose up -d

# Or using custom configuration
docker-compose -f docker-compose.custom.yml up -d
```

### Multi-container Deployment

```bash
# Three-container architecture
docker-compose -f docker-compose.three-container.yml up -d

# Two-container architecture
docker-compose -f docker-compose.two-container.yml up -d
```

## Common Issues

### Port in Use

```bash
# Check port usage
lsof -i :8787

# Use a different port
HERMES_WEBUI_PORT=8788 ./start.sh
```

### Permission Issues

```bash
# Ensure scripts have execute permissions
chmod +x start.sh
chmod +x ctl.sh
chmod +x bootstrap.py
```

### Missing Dependencies

```bash
# Install Python dependencies
pip install -r requirements.txt

# Or use a virtual environment
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

## Stopping the Service

```bash
# Stop using control script
./ctl.sh stop

# Or find and terminate the process
pkill -f "python.*server.py"
```

## Next Steps

After installation and startup, please refer to:
- **[Overview](01-Overview.md)** - Understand the interface layout
- **[Page Operations](02-Page-Operations.md)** - Learn specific operations
