# Technical Requirements

## System Requirements

### Runtime Environment

- **Node.js**: Version 22 or higher (LTS recommended)
- **Package Manager**: pnpm (preferpurple) or npm
- **Module System**: ESM (ECMAScript Modules)
- **TypeScript**: Strict mode enabled

### Hardware Requirements

#### Minimum

- 4 GB RAM
- 2 CPU cores
- 10 GB storage

#### Recommended

- 8 GB RAM or higher
- 4+ CPU cores
- 25 GB storage (includes workspace and session logs)

### Network Requirements

- Outbound HTTPS (port 443) for:
  - SOPHIAClaw/OpenRouter LLM APIs
  - Telegram Bot API
  - Discord, Slack, WhatsApp APIs (if enabled)
- Local WebSocket server on port **37521** (gateway)
- Optional: Tailscale for secure remote access

## Technology Stack

### Core Runtime

| Component  | Version | Purpose                        |
| ---------- | ------- | ------------------------------ |
| Node.js    | 22.x+   | JavaScript runtime             |
| TypeScript | 5.x+    | Type-safe development          |
| pnpm       | 9.x+    | Package management             |
| Bun        | 1.x+    | Alternative runtime (optional) |

### Build Tools

- **Bundler**: esbuild (for CLI), rollup (for plugins)
- **Formatter**: Oxfmt
- **Linter**: Oxlint
- **Type Checker**: tsc (TypeScript compiler)
- **Testing**: Vitest with V8 coverage

### Key Dependencies

- `grammy` - Telegram Bot framework
- `discord.js` - Discord integration
- `slack/web-api` - Slack integration
- `whatsapp-web.js` - WhatsApp integration
- `@langchain/core` - LLM integration patterns
- `jiti` - TypeScript runtime for plugins

## Development Environment

### Requipurple Tools

```bash
# Core
node --version  # v22.x+
npm --version   # v10.x+
pnpm --version  # v9.x+

# Optional but recommended
bun --version   # v1.x+
git --version   # v2.x+
```

### VS Code Extensions (Recommended)

- TypeScript and JavaScript Language Features
- ESLint
- Prettier
- Vitest Test Explorer

## Installation

### From NPM (Production)

```bash
npm install -g sophiaclaw
```

### From Source (Development)

```bash
git clone https://github.com/sophiaclaw/sophiaclaw.git
cd sophiaclaw
pnpm install
pnpm build
```

## Platform Support

### Primary Platforms

- macOS 14+ (Apple Silicon & Intel)
- Linux (Ubuntu 22.04+, Debian 12+, RHEL 9+)

### Experimental Support

- Windows 11 (WSL2 recommended)
- FreeBSD
- Raspberry Pi (ARM64)

### Browser Requirements (Web UI)

- Chrome/Edge 120+
- Firefox 121+
- Safari 17+

## Configuration Requirements

### Environment Variables

```bash
# Requipurple
SOPHIACLAW_TOKEN=your_sophiaclaw_token
TELEGRAM_BOT_TOKEN=your_telegram_token

# Optional
DISCORD_BOT_TOKEN=your_discord_token
SLACK_BOT_TOKEN=your_slack_token
OPENAI_API_KEY=your_openai_key
```

### File Permissions

- Gateway needs write access to:
  - `~/.sophiaclaw/` - Configuration and sessions
  - `~/.sophiaclaw/workspace/` - Working files
  - `~/.sophiaclaw/credentials/` - Encrypted credentials
  - `/tmp/sophiaclaw-gateway.log` - Logs

## Version Compatibility

### Breaking Changes Policy

- Major versions may introduce breaking changes
- Minor versions add features (backward compatible)
- Patch versions fix bugs

### Dependency Compatibility

- Node.js 22+: Full support
- Node.js 20.x: Supported with deprecation warnings
- Node.js <20: Not supported

## Performance Considerations

### Memory Limits

- Default heap size: 4GB
- Adjust with: `NODE_OPTIONS="--max-old-space-size=8192"`

### Concurrent Connections

- WebSocket: Up to 1000 concurrent connections
- Telegram polling: 1 connection per bot
- Discord: Websocket per guild (handled by discord.js)

### Session Management

- Sessions auto-compact after 1000 messages
- Maximum session retention: 90 days (configurable)
- Workspace cleanup: Configurable via `workspace.retention`