AgentMux is in early alpha and under heavy active development. Many features described in these docs may be incomplete, unstable, or not yet implemented. Expect breaking changes between releases. We welcome bug reports and feedback on GitHub Issues or Discord .
AgentMux exposes an RPC API via WebSocket (JSON-RPC 2.0) for communication between the frontend, backend, and wsh shell helper. This page documents the key API commands.
Protocol: WebSocket with JSON-RPC 2.0Backend: agentmuxsrv-rs (Rust, Tokio + Axum)Client: WshClient in the frontend, wsh binary on remote hosts
Command Description createblockCreate a new block (pane) in a tab createsubblockCreate a sub-block within a parent block deleteblockDelete a block deletesubblockDelete a sub-block blockinfoGet block metadata and file info blockslistList all blocks, optionally filtered by window or workspace
Command Description controllerinputSend input to a block’s controller (terminal input, signals, resize) controllerresyncResync or restart a block’s controller controllerstopStop a block’s controller controllerappendoutputAppend output to a block’s controller captureblockscreenshotCapture a screenshot of a block’s content
Command Description filereadRead a file’s contents filewriteWrite contents to a file filecreateCreate a new file filedeleteDelete a file fileappendAppend data to a file filecopyCopy a file filemoveMove/rename a file filemkdirCreate a directory filelistList files in a directory fileliststreamStream a directory listing (for large directories) filereadstreamStream file contents filestreamtarStream a tar archive of files fileinfoGet file metadata filejoinJoin file paths
Command Description eventpublishPublish an event to the event bus eventrecvReceive/handle an event eventsubSubscribe to events by type and scope eventunsubUnsubscribe from a specific subscription eventunsuballUnsubscribe from all subscriptions eventreadhistoryRead historical events
Command Description connconnectConnect to a remote host conndisconnectDisconnect from a remote host connensureEnsure a connection is established connlistList active connections connlistawsList available AWS connections connstatusGet status of all connections connreinstallwshReinstall wsh on a remote host connupdatewshUpdate wsh on a remote host
Command Description aisendmessageSend a message to an AI agent fetchsuggestionsGet AI-generated suggestions disposesuggestionsClean up suggestion resources
Command Description getmetaGet metadata for a wave object setmetaSet metadata on a wave object getfullconfigGet the complete configuration getupdatechannelGet the current update channel getvarGet a variable value setvarSet a variable value
Command Description focuswindowFocus a specific window gettabGet tab information
Command Description authenticateAuthenticate with a token string authenticatetokenAuthenticate with structured token data
Command Description activityReport activity metrics (foreground time, AI requests, block counts, etc.)
Some commands return async streams instead of single responses:
fileliststream — Stream directory entries progressivelyfilereadstream — Stream file contents in chunksfilestreamtar — Stream tar archive data
These use the wshRpcStream method and return AsyncGenerator objects.
The wsh binary provides shell-level access to the API:
wsh view myfile.txt # Open file in a preview pane
wsh edit myfile.txt # Open file in editor pane
The wsh binary communicates with the backend over WebSocket and is automatically deployed to remote hosts on SSH connection.
