Metadata-Version: 2.4
Name: sandd
Version: 0.0.1
Requires-Dist: pytest>=7.0 ; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21 ; extra == 'dev'
Requires-Dist: black>=23.0 ; extra == 'dev'
Requires-Dist: mypy>=1.0 ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: A lightweight sandbox daemon for secure agent execution in isolated environments.
Keywords: agent,daemon,sandbox
Home-Page: https://github.com/InftyAI/SandD
Author-email: InftyAI <contact@inftyai.com>
License: Apache-2.0
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Project-URL: Homepage, https://github.com/InftyAI/SandD
Project-URL: Repository, https://github.com/InftyAI/SandD

<div align="center">

# SandD

**Sandbox Daemon for Agent Command Execution**

[![Rust](https://img.shields.io/badge/rust-1.70+-orange.svg)](https://www.rust-lang.org/)
[![Python](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

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

</div>

---

## 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:
```bash
pip install sandd
```

Or build from source:
```bash
git clone https://github.com/InftyAI/SandD
cd SandD
make install
```

### Daemon Binary (Worker)

#### Quick Install

```bash
# Direct mode (no tunnel)
curl -fsSL https://raw.githubusercontent.com/InftyAI/SandD/main/hack/scripts/install.sh | sudo bash

# Tunnel mode (with Tailscale)
curl -fsSL https://raw.githubusercontent.com/InftyAI/SandD/main/hack/scripts/install.sh | sudo bash -s -- --tunnel
```

This installs the latest release. To pin a specific version:

```bash
curl -fsSL https://raw.githubusercontent.com/InftyAI/SandD/main/hack/scripts/install.sh | sudo bash -s -- --version v0.1.0
```

#### Alternative Methods

**Install from crates.io:**
```bash
cargo install sandd
```

**Build from source:**
```bash
git clone https://github.com/InftyAI/SandD
cd SandD
make daemon-release
# Binary at: ./target/release/sandd
```

**Build from the main branch:**
```bash
cargo install --git https://github.com/InftyAI/SandD sandd
```

## Quick Start

### Direct Mode (Development)

**Start controller:**

```python
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:**

```bash
# 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):

```python
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](./docs/proposals/TUNNEL.md) for setup instructions.

## Documentation

- [Quick Start Guide](./docs/QUICKSTART.md)
- [Architecture Details](./docs/ARCHITECTURE.md)
- [Protocol Specification](./docs/proposals/PROTOCOL.md)
- [Tunnel Mode Guide](./docs/proposals/TUNNEL.md)
- [Development Guide](./docs/DEVELOP.md)
- [Examples](./examples)

## 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](./docs/DEVELOP.md) for development setup and guidelines.

## License

Apache-2.0 — see [LICENSE](./LICENSE).

