# Remux v1 - Getting Started

## Quick Start

### 1. Start the Daemon

```bash
# Default: ~/.rpipe/daemon.sock with auto-detected SSH known_hosts
python -m rpipe.daemon

# Custom socket path
python -m rpipe.daemon /tmp/my-daemon.sock

# Custom socket + known_hosts path
python -m rpipe.daemon /tmp/daemon.sock ~/.ssh/known_hosts

# Or via environment variable
export RPIPE_KNOWN_HOSTS=~/.ssh/known_hosts
python -m rpipe.daemon
```

### 2. Execute Remote Commands

```bash
# Simple read-only command
python -m rpipe.client example.com cat /var/log/syslog

# Search logs
python -m rpipe.client example.com grep error /var/log/syslog

# List directory
python -m rpipe.client example.com ls -la /var/log

# Custom working directory
python -m rpipe.client example.com --cwd /tmp pwd

# With environment variables
python -m rpipe.client example.com --env FOO=bar echo $FOO

# With timeout
python -m rpipe.client example.com --timeout 30 sleep 10
```

## Policy Models

The daemon uses capability-based security policies (v1):

### Read-Only Policy (Default)
```bash
python -m rpipe.client example.com --policy read_only cat /var/log/syslog
```
Allows: `cat`, `grep`, `ls`, `tail`, `head`, `find`, `pwd`, `date`, etc.
Blocks: Any write operations, dangerous commands (`rm`, `chmod`, etc.)

### Write-Capable Policy
```bash
python -m rpipe.client example.com --policy write_capable echo data > /tmp/file
```
Allows: All read operations + writes to `/tmp/*`
Blocks: Dangerous commands, writes outside `/tmp`

### Restrictive Policy
```bash
python -m rpipe.client example.com --policy restrictive date
```
Allows: Only safe system info (`echo`, `date`, `hostname`, etc.)
Blocks: File operations, most commands

## Security

### Host Key Verification (CRITICAL)

The daemon verifies SSH host keys to prevent MITM attacks:

```bash
# Secure: with host key verification
RPIPE_KNOWN_HOSTS=~/.ssh/known_hosts python -m rpipe.daemon

# Insecure: without verification (DEV ONLY!)
python -m rpipe.daemon
```

**IMPORTANT**: Always use proper host key verification in production!

### Command Validation

All commands are validated against the policy before execution:

```bash
# This will be rejected (rm blocked)
python -m rpipe.client example.com rm /tmp/file
# → Policy Error: execute_binary on 'rm' not permitted

# This will be rejected (write operation in read-only)
python -m rpipe.client example.com echo hello > /tmp/file
# → Policy Error: write_file on '/tmp/file' not permitted
```

## Concurrent Clients

The daemon handles multiple concurrent client connections:

```bash
# Client 1
python -m rpipe.client server1.com cat /var/log/syslog

# Client 2 (in another terminal, simultaneous)
python -m rpipe.client server2.com grep error /var/log/auth.log

# Client 3 (in another terminal, simultaneous)
python -m rpipe.client server1.com ls -la /tmp
```

All clients are handled concurrently by the asyncio event loop.

## Architecture Overview

```
Client (CLI)
    ↓ (RPC via Unix socket)
Daemon (Server)
    ├─ Frame Protocol (binary multiplexing)
    ├─ Policy Validation (capability-based)
    ├─ Command Parser (safe extraction)
    └─ SSH Backend (connection pooling)
         ↓ (SSH protocol)
    Remote Host
         ↓ (execute command)
    stdout/stderr/exit code
         ↓
    Back to Client
```

## Testing

Run the test suite:

```bash
# All tests
pytest rpipe/tests/ -v

# Specific module
pytest rpipe/tests/test_capability.py -v

# Coverage
pytest rpipe/tests/ --cov=rpipe
```

**Current Status**: 275 tests passing
- execution_safety: 40 tests
- ssh_backend: 17 tests
- protocol: 23 tests
- daemon: 16 tests
- policy: 34 tests
- client: 17 tests
- command_parser: 48 tests
- capability: 40 tests
- policy_capabilities: 28 tests
- integration_daemon_policy: 12 tests

## Limitations & Known Issues

### v0 Limitations (Fixed in v1):
- ✅ Token-based denylist → Capability-based allowlist
- ✅ Serial client handling → Concurrent clients
- ✅ Host key verification disabled → Now enabled

### Remaining Limitations:
- Command parser doesn't support pipes, conditionals, loops (design choice for safety)
  - Workaround: Use simpler commands or combine with shell filters on remote
- No automatic key exchange; uses existing SSH identities
- Connection pooling is per-host only (no port/username distinction)

## Environment Variables

- `RPIPE_KNOWN_HOSTS`: Path to SSH known_hosts file

## Files

- `rpipe/daemon.py`: Unix socket server
- `rpipe/client.py`: CLI client
- `rpipe/protocol.py`: Binary frame protocol
- `rpipe/capability.py`: Capability model & policies
- `rpipe/command_parser.py`: Safe command parsing
- `rpipe/policy_capabilities.py`: Policy validation
- `rpipe/ssh_backend.py`: SSH connection pooling
- `rpipe/execution.py`: Execution safety validation

## Support

- Issues: See CLAUDE.md for detailed architecture and design notes
- Tests: See test files in `rpipe/tests/`
- Examples: Above in this document
