Castrel Proxy

Castrel Proxy is a lightweight local proxy client. It connects to Castrel over WebSocket, receives instructions from the server, executes them on your machine, and sends results back.

It provides five core capabilities:

• Command execution: run shell commands (governed by workspace policy + local allowlist)
• Document operations: read / write / edit files (with path and size constraints)
• MCP integration: connect to locally configured MCP services and sync available tools to the server
• HTTP proxy access: forward HTTP requests to internal network endpoints through the proxy
• Interactive terminal sessions: support long-running command sessions with incremental output

How it works

Castrel Proxy pairs with the server, keeps a persistent connection, executes tasks locally, and returns results. If you configure MCP, it can also call local MCP tools when needed.

sequenceDiagram
  participant P as castrel-proxy (local)
  participant S as Castrel server
  participant M as MCP servers (local)

  Note over P,S: Pair once, then stay connected
  P->>S: Pair
  S-->>P: Paired
  P->>S: Connect
  S-->>P: Send tasks
  P-->>S: Return results

  Note over P,M: Optional (if configured)
  P->>M: Call local tool
  M-->>P: Tool result

Quick start

Install

Recommended public entry:

curl -fsSL https://castrel.ai/castrel-proxy/install.sh | bash

This installer downloads the platform package from Castrel's public package storage, verifies .sha256, then installs castrel-proxy. For private mirrors, set CASTREL_PROXY_PACKAGE_BASE_URL before running the installer.

Default behavior installs to user-level ~/.local/bin (no sudo).

Use a custom install directory:

curl -fsSL https://castrel.ai/castrel-proxy/install.sh | bash -s -- --install-dir ~/bin

If you do not provide --install-dir in an interactive terminal, the installer asks you to input an installation directory. Leave it empty to use the default ~/.local/bin.

Installer options:

--install-dir <path>   Install into a custom directory

Environment variables are also supported:

CASTREL_INSTALL_DIR=~/.local/bin

If your chosen directory is not in $PATH, the installer prints a command you can add to your shell rc file.

When you use --install-dir, the installer also checks PATH and gives clear guidance so the binary can be found in new shells.

curl -fsSL https://castrel.ai/castrel-proxy/install.sh | bash

pip install castrel-proxy

Requirement: Python >= 3.10

Pair

Get a verification code and server URL from your Castrel admin UI, then run:

castrel-proxy pair <verification_code> <server_url>

After pairing, Castrel Proxy will:

• Save pairing config to ~/.castrel/config.yaml
• Initialize command whitelist at ~/.castrel/whitelist.conf
• Attempt to read ~/.castrel/mcp.json and sync MCP tool info once (skipped if not configured)

Start

# Background daemon mode (default, Unix/macOS only)
castrel-proxy start

# Foreground mode (all platforms)
castrel-proxy start --foreground

Status and logs

castrel-proxy status
castrel-proxy logs
castrel-proxy logs -f

Stop / unpair

castrel-proxy stop
castrel-proxy unpair

Configuration and file locations

By default, Castrel Proxy uses ~/.castrel/:

• Proxy config: ~/.castrel/config.yaml
  • server_url: server URL
  • verification_code: pairing code
  • client_id: stable ID derived from hostname + MAC (16 hex chars)
  • workspace_id: extracted from the verification code
  • paired_at: pairing timestamp
• Command whitelist: ~/.castrel/whitelist.conf
  • One allowed base command per line (e.g. git, kubectl)
• MCP config (optional): ~/.castrel/mcp.json
• Daemon files (background mode):
  • PID: ~/.castrel/castrel-proxy.pid
  • Log: ~/.castrel/castrel-proxy.log
• Per-session logs (written when server sends tasks):
  • ~/.castrel/<session_id>/terminal.log

Core capabilities (as implemented)

1) Command execution (command_line + policy checks)

When the server sends a local_tool_call, Castrel Proxy executes a single command_line string locally and returns stdout, stderr, exit_code, and timing.

Security behavior (in order):

• Workspace policy deny_all: all shell execution is blocked
• Workspace policy allowlist: every subcommand must pass the server allowlist
• Workspace policy passthrough: local whitelist ~/.castrel/whitelist.conf is applied

Compound commands like ls && cat file | grep foo are parsed and validated command by command.

2) Document operations (read / write / edit)

Castrel Proxy supports:

• Read a file
• Overwrite-write a file
• Edit a file with replace / append / prepend

Constraints:

• Paths must be absolute
• Read size limit is 10MB
• Runs with your user permissions (no privilege escalation)
• Can be disabled by workspace policy (read_enabled / write_enabled / edit_enabled)

3) MCP (Model Context Protocol) integration

If you want to expose local MCP tools to the server, configure ~/.castrel/mcp.json and use:

castrel-proxy mcp-list
castrel-proxy mcp-sync

Supported transports (as implemented):

• stdio (requires command + args, optional env)
• http (requires url)
• sse (requires url)

4) HTTP proxy for internal endpoints

Castrel Proxy can execute http_proxy_call from the server and return the upstream status/body to Castrel. This is used to access internal observability endpoints (for example intranet Prometheus) without exposing them publicly.

HTTP forwarding is controlled by workspace policy (http.enabled, optional http.allow_hosts).

5) Interactive local execution

Castrel Proxy supports local_interactive_call for start/write/read/stop style command sessions, which is useful for commands that require incremental interaction.

When to use Castrel Proxy

• Local troubleshooting: bring local command output and local files into a remote investigation flow
• Controlled remote collaboration: keep execution limited to your approved whitelist
• Castrel Proxy local MCP tools: filesystem/github/internal HTTP MCP services, etc.

FAQ

Does Castrel Proxy open inbound ports on my machine?

No. It makes an outbound WebSocket connection to the server and does not require inbound ports.

How do I allow an additional command?

Add the base command name to ~/.castrel/whitelist.conf (one per line). For example, to allow kubectl get pods, add kubectl.

Why did file reading fail?

Common reasons:

• The path is not absolute
• The file is larger than 10MB
• Your user does not have read permission

How do I uninstall?

Stop the proxy, uninstall, and remove all local configs and logs:

castrel-proxy stop
rm -f "$(command -v castrel-proxy)"
rm -rf ~/.castrel

castrel-proxy stop
pip uninstall castrel-proxy
rm -rf ~/.castrel