Skip to content

README.md

Latest commit

 

History

History
176 lines (133 loc) · 5.46 KB

README.md

File metadata and controls

176 lines (133 loc) · 5.46 KB

SandD

Sandbox Daemon for Agent Command Execution

Rust Python License: MIT

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
  • Tunnel Mode (VPN) - Secure mesh networking with WireGuard encryption via Tailscale
  • 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
                     │ (ws:// in direct mode, encrypted via VPN in tunnel mode)
                     │
           ┌─────────┼─────────┐
           │         │         │
       ┌───▼───┐ ┌───▼───┐ ┌───▼───┐
       │Daemon │ │Daemon │ │Daemon │
       │  #1   │ │  #2   │ │  #n   │
       └───────┘ └───────┘ └───────┘

Installation

Python Package (Controller)

Install from PyPI:

pip install sandd

Or build from source:

git clone https://github.com/InftyAI/SandD
cd SandD
make install

Daemon Binary (Worker)

Quick Install

# Direct mode (no tunnel)
curl -fsSL https://get.sandd.dev/install.sh | sudo bash

# Tunnel mode (with Tailscale)
curl -fsSL https://get.sandd.dev/install.sh | sudo bash -s -- --tunnel

Alternative Methods

Install from crates.io:

cargo install sandd

Build from source:

git clone https://github.com/InftyAI/SandD
cd SandD
make daemon-release
# Binary at: ./target/release/sandd

Quick Start

Direct Mode (Development)

Start controller:

from sandd import Server

server = Server()  # Direct mode (default)
server.wait_for_daemon("worker-1", timeout=30)

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

Start daemon:

# Direct mode
sandd --server-url ws://controller-ip:8765/ws --daemon-id worker-1

# Tunnel mode
sandd --server-url ws://10.200.0.1:8765/ws \
      --daemon-id worker-1 \
      --tunnel \
      --tunnel-authkey YOUR_KEY \
      --tunnel-server http://headscale:8080

Tunnel Mode (Production)

For secure multi-cloud deployments with mesh VPN (no TLS setup needed):

from sandd import Server, TunnelConfig

config = TunnelConfig(
    authkey="YOUR_KEY",
    server="http://headscale:8080",
)
server = Server(connect="tunnel", tunnel_config=config)
# ✓ Encrypted with WireGuard (no TLS needed)
# ✓ Works across NAT/firewalls
# ✓ No public IPs required

See Tunnel Mode Guide for setup instructions.

Documentation

Roadmap

  • 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