Castrel Proxy

A lightweight remote command execution bridge client that connects to a server via WebSocket to receive and execute commands, with MCP (Model Context Protocol) integration.

✨ Features

• ✅ Secure Pairing: Pair with server using verification codes
• ✅ Persistent Configuration: Configuration saved in ~/.castrel/config.yaml
• ✅ Unique Identifier: Generate stable client ID based on machine characteristics
• ✅ WebSocket Connection: Real-time bidirectional communication
• ✅ Command Execution: Execute shell commands with whitelist security
• ✅ Document Operations: Read, write, and edit files remotely
• ✅ Auto Reconnect: Automatically reconnect when connection is lost
• ✅ Timeout Control: Command execution timeout protection
• ✅ MCP Integration: Connect to local MCP services and sync tools information

📦 Installation

Via pip

pip install castrel-proxy

From source

git clone https://github.com/castrel-ai/castrel-proxy.git
cd castrel-proxy
pip install -e .

🚀 Quick Start

1. Pair with Server

castrel-proxy pair <verification_code> <server_url>

Example:

castrel-proxy pair eyJ0cyI6MTczNTA4ODQwMCwid2lkIjoiZGVmYXVsdCIsInJhbmQiOiIxMjM0NTYifQ https://server.example.com

2. Start Bridge Service

# Run in background (default)
castrel-proxy start

# Run in foreground
castrel-proxy start --foreground

# Press Ctrl+C to stop (foreground mode only)

3. Stop Bridge Service

# Stop background daemon
castrel-proxy stop

4. Check Status

castrel-proxy status

5. View Logs

# View last 50 lines (default)
castrel-proxy logs

# View last 100 lines
castrel-proxy logs -n 100

# Follow logs in real-time
castrel-proxy logs -f

🛠️ Managing Skills

Create a skill scaffold:

castrel-bridge-cli skill init my-skill -d "my custom skill"

List local skills:

castrel-bridge-cli skill list -v

Validate a skill:

castrel-bridge-cli skill validate my-skill --strict

Package / Import a skill:

castrel-bridge-cli skill package my-skill -o /tmp/my-skill.skill
castrel-bridge-cli skill import /tmp/my-skill.skill

Sync skills to server:

castrel-bridge-cli skill sync

Skill Sync Troubleshooting

• 401/403: Re-run castrel-bridge-cli pair and verify the code and workspace match.
• skill_content_pull fails with content_hash mismatch: Server content has changed — retry sync or check if server is caching an old hash.
• Import fails with "directory name does not match frontmatter name": Rename the directory to exactly match the name field in SKILL.md.
• Import fails with "forbidden file type": Remove .pem/.key/.dll/.so and other restricted files before importing.
• Skills not visible on server after sync: Confirm castrel-bridge-cli skill list -v shows local skills, then run castrel-bridge-cli mcp-sync or skill sync.

📖 Documentation

• Installation Guide
• Configuration Guide
• Daemon Mode Guide
• MCP Integration
• API Reference
• Protocol Specification
• Migration Guide

🔧 Configuration

Bridge Configuration (~/.castrel/config.yaml)

Pairing information is saved automatically:

server_url: "https://server.example.com"
verification_code: "ABC123"
client_id: "a1b2c3d4e5f6"
workspace_id: "default"
paired_at: "2025-12-22T10:30:00Z"

MCP Configuration (~/.castrel/mcp.json)

Configure MCP services (optional):

{
  "mcpServers": {
    "filesystem": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"],
      "env": {}
    }
  }
}

See examples/mcp.json.example for more examples.

Command Whitelist (~/.castrel/whitelist.conf)

Configure allowed commands for security:

# Add commands one per line
ls
cat
git
python
# etc.

🏗️ Architecture

┌─────────────────────────────────────────────────┐
│           Bridge Client (Local)                 │
│                                                 │
│  ┌──────────────────────────────────────────┐  │
│  │         CLI Commands                     │  │
│  └──────────────────────────────────────────┘  │
│                    │                            │
│      ┌─────────────┼─────────────┐              │
│      │             │             │              │
│  ┌───▼────┐  ┌────▼─────┐  ┌───▼─────┐        │
│  │ Core   │  │   MCP    │  │ Network │        │
│  │ Config │  │  Manager │  │ Client  │        │
│  └────────┘  └──────────┘  └──────────┘        │
│                    │             │              │
│              ┌─────▼─────┐       │              │
│              │   MCP     │       │              │
│              │  Servers  │       │              │
│              └───────────┘  ┌────▼─────┐       │
│                             │ Command  │       │
│                             │ Executor │       │
│                             └──────────┘       │
└─────────────────────────────────────────────────┘
                              │
                              │ WebSocket
                              ▼
┌─────────────────────────────────────────────────┐
│            Bridge Server (Remote)               │
│  /api/v1/bridge/ws?client_id=xxx&code=yyy       │
└─────────────────────────────────────────────────┘

🛠️ Development

Setup Development Environment

# Clone repository
git clone https://github.com/castrel-ai/castrel-proxy.git
cd castrel-proxy

# Install dependencies and sync environment
uv sync

Run Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=castrel_proxy

# Run specific test file
pytest tests/test_core.py

Code Quality

# Format code
black src/

# Lint code
flake8 src/

# Type checking
mypy src/

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

📝 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔒 Security

For security concerns, please see SECURITY.md or contact security@example.com.

📮 Contact

• Issues: GitHub Issues
• Discussions: GitHub Discussions

🙏 Acknowledgments

• Built with Typer for CLI
• Uses aiohttp for async WebSocket communication
• Integrates with MCP for tool protocols