SandD

Sandbox Daemon for Agent Command Execution

Rust-powered WebSocket server with Python API for remote command execution and interactive sessions.

---

Features

• Command Execution - Run shell commands on remote machines with timeout control
• Interactive Sessions - Full PTY sessions with bash for manual work
• File Transfer - Upload/download files between controller and workers
• High Performance - Rust async runtime handles high-concurrency workloads
• Auto Reconnection - Workers reconnect automatically on network failures
• Cross-Platform - Linux, macOS, Windows support

Architecture

┌──────────────────────────────────────────┐
│  Python Agent Application                │
│  ┌────────────────────────────────────┐  │
│  │  from sandd import Server          │  │
│  │                                    │  │
│  │  server = Server("0.0.0.0", 8765)  │  │
│  │  result = server.exec(             │  │
│  │      "daemon-1", "ls -la"          │  │
│  │  )                                 │  │
│  └────────────────────────────────────┘  │
│          ▲                               │
│          │ Python bindings (PyO3)        │
│          ▼                               │
│  ┌────────────────────────────────────┐  │
│  │  Rust WebSocket Server (tokio)     │  │
│  │  • Command routing                 │  │
│  │  • Session management              │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘
                     ▲
                     │ WebSocket (WSS)
                     │ (Daemon initiates connection)
                     │
           ┌─────────┼─────────┐
           │         │         │
       ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
       │Daemon │ │Daemon │ │Daemon │
       │  #1   │ │  #2   │ │  #n   │
       └───────┘ └───────┘ └───────┘

Key Design: Daemons connect TO the agent (not the other way around), so no ports need to be exposed on the execution plane.

Quick Start

# Build
make install          # Python package
make daemon-release   # Worker binary

Start controller:

from sandd import Server

server = Server("0.0.0.0", 8765)
server.wait_for_daemon("worker-1", timeout=30)

result = server.exec("worker-1", "hostname")
print(result.stdout)

Start worker:

./target/release/sandd \
    --server-url ws://controller:8765/ws \
    --daemon-id worker-1

Documentation

• Quick Start Guide
• Architecture Details
• Protocol Specification
• Development Guide
• Examples

Security

⚠️ Add security layers for production use:

• Use wss:// (TLS) instead of plain ws://
• Add authentication (tokens, mTLS)
• Run workers in containers
• Validate commands before execution
• Audit log all commands

Roadmap

• Authentication - Token-based auth for daemon connections
• TLS Support - Built-in WSS with certificate management
• Audit Logging - Track all commands, sessions, and file transfers
• Metrics - Prometheus-compatible metrics for monitoring
• Resource Limits - CPU/memory/timeout controls per daemon
• Multi-tenancy - Isolated workspaces with access control
• Rate Limiting - Prevent abuse and resource exhaustion
• Command Allowlist - Restrict allowed commands per daemon

Contributing

We welcome any kind of contributions, feedback, and suggestions! See DEVELOP.md for development setup and guidelines.

License

MIT