Proxy Reference

Crate pocketcoder_proxy

Version: 0.1.0

Sentinel Proxy

Rust-based bridge that hardens execution calls and provides MCP access.

This sentinel acts as the “Muscle” of the PocketCoder architecture, ensuring that tools are executed within a secure sandbox environment.

Core Components

• Execution Driver: Manages tmux sessions and command execution in the sandbox.
• MCP Proxy: Bridges WebSocket-based Model Context Protocol requests.
• Shell Bridge: Implements the pocketcoder shell command-line interface.

Architecture

The proxy runs as a high-performance Rust service that exposes an SSE and WebSocket API. It translates high-level AI intents into low-level sandbox commands while maintaining isolation and security.

Contents

• Modules
  • driver
  • shell
• Types
  • AppState
  • Cli
  • McpQuery
  • Commands
  • SessionMap
• Functions
  • exec_handler
  • health_handler
  • main
  • sse_handler

Quick Reference

Item	Kind	Description
driver	mod	# Execution Driver This module manages the lifecycle of the sandbox execution environment via tmux socket interaction.
shell	mod	# Shell Bridge This module provides the client-side logic for the pocketcoder shell command, which routes commands from the reasoning engine to the persistent proxy.
AppState	struct
Cli	struct
McpQuery	struct	Query parameters for established sessions.
Commands	enum
exec_handler	fn
health_handler	fn
main	fn
sse_handler	fn
SessionMap	type

Modules

• driver — # Execution Driver
• shell — # Shell Bridge

---

Types

AppState

struct AppState {
    pub sessions: std::sync::Arc<parking_lot::RwLock<std::collections::HashMap<String, mpsc::Sender<serde_json::Value>>>>,
    pub driver: std::sync::Arc<crate::driver::PocketCoderDriver>,
}

Trait Implementations

impl<A, B> HttpServerConnExec<A, B> for AppState

impl Instrument for AppState

impl<V> VZip<V> for AppState

• fn vzip(self) -> V

impl WithSubscriber for AppState

Cli

struct Cli {
    command: Commands,
}

Trait Implementations

impl Args for Cli

• fn group_id() -> Option<clap::Id>

• fn augment_args<'b>(__clap_app: clap::Command) -> clap::Command

• fn augment_args_for_update<'b>(__clap_app: clap::Command) -> clap::Command

impl CommandFactory for Cli

• fn command<'b>() -> clap::Command

• fn command_for_update<'b>() -> clap::Command

impl FromArgMatches for Cli

• fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<Self, clap::Error>

• fn from_arg_matches_mut(__clap_arg_matches: &mut clap::ArgMatches) -> ::std::result::Result<Self, clap::Error>

• fn update_from_arg_matches(&mut self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>

• fn update_from_arg_matches_mut(&mut self, __clap_arg_matches: &mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>

impl<A, B> HttpServerConnExec<A, B> for Cli

impl Instrument for Cli

impl Parser for Cli

impl<V> VZip<V> for Cli

• fn vzip(self) -> V

impl WithSubscriber for Cli

McpQuery

struct McpQuery {
    pub session_id: Option<String>,
}

Query parameters for established sessions.

Fields

• session_id: Option<String>

  Optional session ID to resume or identify the connection

Trait Implementations

impl Deserialize<'de> for McpQuery

• fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

impl DeserializeOwned for McpQuery

impl<A, B> HttpServerConnExec<A, B> for McpQuery

impl Instrument for McpQuery

impl<V> VZip<V> for McpQuery

• fn vzip(self) -> V

impl WithSubscriber for McpQuery

Commands

enum Commands {
    Server {
        port: String,
    },
    Shell {
        command: Option<String>,
        args: Vec<String>,
    },
}

Variants

• Server

  Start the proxy server (MCP Relay + Execution Bridge)

• Shell

  Run in shell bridge mode (client)

Trait Implementations

impl FromArgMatches for Commands

• fn from_arg_matches(__clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<Self, clap::Error>

• fn from_arg_matches_mut(__clap_arg_matches: &mut clap::ArgMatches) -> ::std::result::Result<Self, clap::Error>

• fn update_from_arg_matches(&mut self, __clap_arg_matches: &clap::ArgMatches) -> ::std::result::Result<(), clap::Error>

• fn update_from_arg_matches_mut<'b>(&mut self, __clap_arg_matches: &mut clap::ArgMatches) -> ::std::result::Result<(), clap::Error>

impl<A, B> HttpServerConnExec<A, B> for Commands

impl Instrument for Commands

impl Subcommand for Commands

• fn augment_subcommands<'b>(__clap_app: clap::Command) -> clap::Command

• fn augment_subcommands_for_update<'b>(__clap_app: clap::Command) -> clap::Command

• fn has_subcommand(__clap_name: &str) -> bool

impl<V> VZip<V> for Commands

• fn vzip(self) -> V

impl WithSubscriber for Commands

SessionMap

type SessionMap = std::sync::Arc<parking_lot::RwLock<std::collections::HashMap<String, mpsc::Sender<serde_json::Value>>>>;

---

Functions

exec_handler

async fn exec_handler(__arg0: axum::extract::State<std::sync::Arc<AppState>>, __arg1: axum::Json<crate::driver::ExecRequest>) -> axum::Json<serde_json::Value>

Types: AppState, ExecRequest

health_handler

async fn health_handler() -> &'static str

main

fn main() -> anyhow::Result<()>

sse_handler

async fn sse_handler(__arg0: axum::extract::State<std::sync::Arc<AppState>>, __arg1: axum::extract::Query<McpQuery>) -> axum::response::sse::Sse<impl Stream<Item = anyhow::Result<axum::response::sse::Event, std::convert::Infallible>>>

Types: AppState, McpQuery

---

Module: driver

pocketcoder_proxy / driver

---

Module driver

Execution Driver

This module manages the lifecycle of the sandbox execution environment via tmux socket interaction.

Quick Reference

Item	Kind	Description
CommandResult	struct	Result of a command execution in the sandbox.
ExecRequest	struct	Request to execute a command.
ExecResponse	struct
PocketCoderDriver	struct
default_agent_name	fn

Types

CommandResult

struct CommandResult {
    pub output: String,
    pub exit_code: i32,
}

Result of a command execution in the sandbox.

Fields

• output: String

  Combined stdout and stderr

• exit_code: i32

  Unix exit code

Trait Implementations

impl Clone for CommandResult

• fn clone(&self) -> CommandResult — CommandResult

impl Debug for CommandResult

• fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

impl Deserialize<'de> for CommandResult

• fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

impl DeserializeOwned for CommandResult

impl<T> FromRef<T> for CommandResult

• fn from_ref(input: &T) -> T

impl<A, B> HttpServerConnExec<A, B> for CommandResult

impl Instrument for CommandResult

impl Serialize for CommandResult

• fn serialize<__S>(&self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>

impl<V> VZip<V> for CommandResult

• fn vzip(self) -> V

impl WithSubscriber for CommandResult

ExecRequest

struct ExecRequest {
    pub cmd: String,
    pub cwd: String,
    pub usage_id: Option<String>,
    pub session_id: Option<String>,
    pub agent_name: String,
}

Request to execute a command.

Fields

• cmd: String

  Bash command string

• cwd: String

  Working directory relative to workspace root

• usage_id: Option<String>

  Internal audit ID

• session_id: Option<String>

  Session identifier

• agent_name: String

  Agent identity executing the command (e.g., “poco”)

Trait Implementations

impl Clone for ExecRequest

• fn clone(&self) -> ExecRequest — ExecRequest

impl Debug for ExecRequest

• fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

impl Deserialize<'de> for ExecRequest

• fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

impl DeserializeOwned for ExecRequest

impl<T> FromRef<T> for ExecRequest

• fn from_ref(input: &T) -> T

impl<A, B> HttpServerConnExec<A, B> for ExecRequest

impl Instrument for ExecRequest

impl Serialize for ExecRequest

• fn serialize<__S>(&self, __serializer: __S) -> _serde::__private228::Result<<__S as >::Ok, <__S as >::Error>

impl<V> VZip<V> for ExecRequest

• fn vzip(self) -> V

impl WithSubscriber for ExecRequest

ExecResponse

struct ExecResponse {
    pub stdout: Option<String>,
    pub exit_code: Option<i32>,
    pub error: Option<String>,
}

Trait Implementations

impl Debug for ExecResponse

• fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

impl Deserialize<'de> for ExecResponse

• fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

impl DeserializeOwned for ExecResponse

impl<A, B> HttpServerConnExec<A, B> for ExecResponse

impl Instrument for ExecResponse

impl<V> VZip<V> for ExecResponse

• fn vzip(self) -> V

impl WithSubscriber for ExecResponse

PocketCoderDriver

struct PocketCoderDriver {
    pub socket_path: String,
    pub session_name: String,
}

Implementations

• fn new(socket: &str, session: &str) -> Self

• fn session_exists(&self, session: &str) -> bool

• async fn exec(&self, cmd: &str, cwd: Option<&str>, agent_name: &str) -> Result<CommandResult> — CommandResult

  Execute a command in the target agent’s isolated tmux workspace.

  The proxy strictly targets pocketcoder:[agent_name]:terminal.

Trait Implementations

impl Debug for PocketCoderDriver

• fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result

impl Deserialize<'de> for PocketCoderDriver

• fn deserialize<__D>(__deserializer: __D) -> _serde::__private228::Result<Self, <__D as >::Error>

impl DeserializeOwned for PocketCoderDriver

impl<A, B> HttpServerConnExec<A, B> for PocketCoderDriver

impl Instrument for PocketCoderDriver

impl<V> VZip<V> for PocketCoderDriver

• fn vzip(self) -> V

impl WithSubscriber for PocketCoderDriver

---

Functions

default_agent_name

fn default_agent_name() -> String

---

Module: shell

pocketcoder_proxy / shell

---

Module shell

Shell Bridge

This module provides the client-side logic for the pocketcoder shell command, which routes commands from the reasoning engine to the persistent proxy.

Quick Reference

Item	Kind	Description
run	fn

Functions

run

fn run(command: Option<String>, args: Vec<String>) -> anyhow::Result<()>