API Reference

Python API

Controller Class

class RemotelyPyController:
    def __init__(
        self,
        host: str = '0.0.0.0',
        port: int = 5555,
        use_ssl: bool = False,
        cert_file: Optional[str] = None,
        key_file: Optional[str] = None,
        auth_token: Optional[str] = None
    ) -> None:
        """Initialize controller instance."""

    def start(self) -> bool:
        """Start the controller server."""

    def stop(self) -> None:
        """Stop the controller and disconnect clients."""

    def get_clients(self) -> List[Dict[str, Any]]:
        """Get list of connected clients."""

    def send_command(
        self,
        command: str,
        client_ids: Optional[List[str]] = None
    ) -> Dict[str, str]:
        """Send command to specified clients."""

    def broadcast_message(
        self,
        message: Dict[str, Any],
        exclude: Optional[ClientConnection] = None
    ) -> None:
        """Broadcast message to all clients."""

Client Class

class RemotelyPyClient:
    def __init__(
        self,
        server_host: str,
        server_port: int,
        use_ssl: bool = False,
        ssl_cert: Optional[str] = None,
        reconnect_delay: int = 5,
        client_id: Optional[str] = None
    ) -> None:
        """Initialize client instance."""

    def connect(self) -> bool:
        """Connect to controller server."""

    def run(self) -> None:
        """Start client main loop."""

    def execute_command(self, command: str) -> Dict[str, Any]:
        """Execute shell command and return result."""

Command-Line Interface

Controller Commands

remotelypy controller [OPTIONS]

Options:

Option	Type	Default	Description
--host	str	0.0.0.0	Host interface to bind to
--port	int	5555	Port to listen on
--ssl	flag	False	Enable SSL encryption
--cert	str	None	SSL certificate file
--key	str	None	SSL private key file
--log-level	str	INFO	Logging level
--daemon	flag	False	Run in daemon mode
--log-file	str	None	Log file path
--pid-file	str	None	PID file path

Client Commands

remotelypy client [OPTIONS]

Options:

Option	Type	Default	Description
--host	str	Required	Controller hostname/IP
--port	int	5555	Controller port
--ssl	flag	False	Enable SSL encryption
--cert	str	None	SSL certificate path
--id	str	Auto	Client identifier
--reconnect-delay	int	5	Reconnection delay seconds
--log-level	str	INFO	Logging level

Message Protocol

Message Format

All messages are JSON-formatted and newline-delimited:

{
  "type": "string",      // Message type
  "timestamp": number,   // Unix timestamp
  "data": object        // Message-specific payload
}

Message Types

Registration

{
  "type": "registration",
  "system_info": {
    "hostname": "string",
    "platform": "string",
    "platform_version": "string",
    "python_version": "string",
    "client_id": "string",
    "ip_address": "string"
  }
}

Command

{
  "type": "command",
  "command_id": "string",
  "command": "string"
}

Command Result

{
  "type": "command_result",
  "command_id": "string",
  "result": {
    "status": "success|error",
    "exit_code": number,
    "stdout": "string",
    "stderr": "string",
    "cwd": "string"
  }
}

Ping/Pong

{
  "type": "ping|pong",
  "timestamp": number
}

Event System

Controller Events

class ControllerEvents:
    def on_client_connected(client: ClientConnection) -> None:
        """Called when new client connects."""

    def on_client_disconnected(client: ClientConnection) -> None:
        """Called when client disconnects."""

    def on_command_executed(
        client: ClientConnection,
        command: str,
        result: Dict[str, Any]
    ) -> None:
        """Called when command execution completes."""

Client Events

class ClientEvents:
    def on_connected() -> None:
        """Called when connected to controller."""

    def on_disconnected() -> None:
        """Called when disconnected from controller."""

    def on_command_received(command: str) -> None:
        """Called when command is received."""

Error Handling

Error Types

class RemotelyPyError(Exception):
    """Base exception class."""
    pass

class ConnectionError(RemotelyPyError):
    """Connection-related errors."""
    pass

class CommandError(RemotelyPyError):
    """Command execution errors."""
    pass

class AuthenticationError(RemotelyPyError):
    """Authentication-related errors."""
    pass

Error Responses

{
  "type": "error",
  "error": {
    "code": "string",
    "message": "string",
    "details": object
  }
}

Type Definitions

from typing import TypedDict, Literal

class SystemInfo(TypedDict):
    hostname: str
    platform: str
    platform_version: str
    python_version: str
    client_id: str
    ip_address: str

class CommandResult(TypedDict):
    status: Literal["success", "error"]
    exit_code: Optional[int]
    stdout: str
    stderr: str
    cwd: str