npm package: @mjasano/devtunnel
Description: Web terminal with code editor and tunnel manager - access your dev environment from anywhere
Latest version: 1.5.5

# DevTunnel

Web-based terminal with integrated code editor and Cloudflare tunnel management. Access your development environment from anywhere.

## Features

- **Web Terminal**: Full-featured terminal with xterm.js
  - Multiple terminal sessions with tabs
  - Session persistence (24h timeout)
  - tmux session integration
- **Code Editor**: Monaco Editor (VS Code engine)
  - File explorer with breadcrumb navigation
  - 20+ language syntax highlighting
  - Multi-file tabs with unsaved change indicators
  - Keyboard shortcuts (Ctrl+S to save)
- **Tunnel Manager**: Expose local ports via Cloudflare
  - Quick tunnel creation
  - Real-time status updates
  - Copy-to-clipboard functionality
- **System Monitor**: Real-time resource monitoring
  - CPU and memory usage
  - Uptime and load average

## Installation

```bash
npm install -g @mjasano/devtunnel
```

### Prerequisites

- Node.js 18+
- cloudflared (auto-installed on macOS/Linux)

## Usage

```bash
# Start DevTunnel with tunnel
devtunnel

# Use custom port
devtunnel --port 8080

# Enable passcode authentication (auto-generated)
devtunnel --passcode

# Enable passcode authentication (custom)
devtunnel --passcode=MYCODE

# Show help
devtunnel --help

# Show version
devtunnel --version
```

## Authentication

When running with `--passcode`, DevTunnel requires authentication:

- A login page is shown before accessing the terminal
- Passcode is displayed in the CLI output when auto-generated
- Sessions remain authenticated for 24 hours
- Use the Logout button in the header to end your session

## Development

```bash
# Clone the repository
git clone https://github.com/mjasano/web-terminal.git
cd web-terminal

# Install dependencies
npm install

# Start development server
npm start
```

## Docker

```bash
# Build and run
docker-compose up -d

# Or with Docker
docker build -t devtunnel .
docker run -p 3000:3000 -v $(pwd):/workspace devtunnel
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `PORT` | Server port | 3000 |
| `WORKSPACE` | Root directory for file browser | Home directory |
| `PASSCODE` | Authentication passcode | None (no auth) |

## API Endpoints

### REST API

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/auth/status` | Check auth status |
| POST | `/api/auth/login` | Login with passcode |
| POST | `/api/auth/logout` | Logout |
| GET | `/api/system` | System information |
| GET | `/api/files` | File listing |
| GET | `/api/files/read` | Read file content |
| POST | `/api/files/write` | Write file content |
| POST | `/api/files/delete` | Delete file/directory |
| POST | `/api/files/rename` | Rename file/directory |
| GET | `/api/sessions` | Terminal sessions |
| DELETE | `/api/sessions/:id` | Kill session |
| GET | `/api/tunnels` | Active tunnels |
| POST | `/api/tunnels` | Create tunnel |
| DELETE | `/api/tunnels/:id` | Stop tunnel |
| GET | `/health` | Health check |

### WebSocket Messages

| Type | Direction | Description |
|------|-----------|-------------|
| `attach` | Client | Attach to session |
| `detach` | Client | Detach from session |
| `input` | Client | Terminal input |
| `resize` | Client | Terminal resize |
| `create-tunnel` | Client | Create tunnel |
| `stop-tunnel` | Client | Stop tunnel |
| `output` | Server | Terminal output |
| `attached` | Server | Session attached |
| `sessions` | Server | Session list |
| `tunnels` | Server | Tunnel list |

## License

MIT