🔐 Pastebox Engine

Production-grade distributed encrypted file vault with native containerization

A high-performance, secure file sharing platform built in Go, featuring distributed cluster architecture, MongoDB persistence, native container virtualization, time-bombed storage, military-grade encryption, SSH/SFTP access, and a modern React dashboard.

🌟 Features at a Glance

Feature	Description
🌐 Distributed Cluster	Master/slave architecture with automatic load balancing
💾 MongoDB Persistence	Stateful storage with automatic instance restoration
🐳 Native Virtualization	Docker-like isolation without Docker (cgroups + namespaces)
🔐 Military-Grade Encryption	ChaCha20-Poly1305, AES-256-GCM with Argon2id KDF
📁 Unified File Management	Files, Pastes & Secrets in one interface
🖥️ SSH/SFTP Access	Full shell with 20+ commands
🌐 Modern Web Dashboard	React-based UI with real-time monitoring
⏰ Time-Bombed Storage	Auto-delete after configurable TTL
📊 Health Monitoring	Real-time CPU, memory, disk tracking with Recharts
🔍 Deep Inspection	Per-node and per-box drill-down capabilities
🖥️ WebSocket Terminal	Browser-based shell access (works on any cloud platform)
⚡ Code Execution API	HTTP API to run Python, Node, Go, Rust, C, Ruby, PHP, Bash
☁️ Cloud Storage (S3/R2)	Scalable storage backend for horizontal scaling
📦 Per-Box Runtimes	Isolated language installations per pastebox
🛡️ Security Hardening	seccomp, capabilities, namespaces, cgroups limits

🚀 Quick Start

Prerequisites

Go 1.21+ - Download
Node.js 18+ - Download (for dashboard)
MongoDB 7.0+ - Download
rclone - Required for S3/R2 cloud storage (brew install rclone or apt install rclone)
macOS or Linux (Windows via WSL2)

Installation (Production)

# Clone repository
git clone https://github.com/Pastezen/Pastebox.git
cd Pastebox

# Start MongoDB (if not running)
mongod --dbpath ./data/mongodb

# Build backend
go mod download
go build -o router ./cmd/router

# Build frontend (production)
cd client
npm install
npm run build
cd ..

# Create data directories
mkdir -p data/storage data/mongodb

# Create config (optional - defaults work out of box)
cp config.yaml.example config.yaml

# Run
./router

Development Setup

# Terminal 1: MongoDB
mongod --dbpath ./data/mongodb

# Terminal 2: Backend
go build -o router ./cmd/router && ./router

# Terminal 3: Frontend (with hot reload)
cd client
npm install
npm run dev

First Run Checklist

Step	Command/Action	Notes
1. Start MongoDB	`mongod --dbpath ./data/mongodb`	Required for persistence
2. Start backend	`./router`	Listens on 8080, SSH on 2222
3. Start frontend	`cd client && npm run dev`	Dashboard at localhost:5173
4. Create pastebox	Click "Create Pastebox" in UI	Note the box ID (e.g., `box-123...`)
5. Test SSH	`ssh box-ID@localhost -p 2222`	First time: accept host key

Access Points

Service	URL/Port	Description
Web Dashboard	http://localhost:5173	React UI (dev mode)
REST API	http://localhost:8080/api	Backend API
SSH Shell	`ssh box-ID@localhost -p 2222`	Full shell access
SFTP	`sftp -P 2222 box-ID@localhost`	File transfer
Cluster API	http://localhost:8080/api/cluster	Cluster management

Troubleshooting

Issue	Solution
MongoDB connection failed	Ensure MongoDB is running on port 27017
Port 8080 in use	Change `server.port` in config.yaml
Port 2222 in use	Change `server.ssh_port` in config.yaml
SSH host key changed	`ssh-keygen -R "[localhost]:2222"`
Frontend can't connect	Ensure backend is running on 8080
Permission denied	Check `data/storage` permissions

🌐 Cluster Architecture

Pastebox supports distributed master/slave architecture for high availability and horizontal scaling.

Architecture Overview

┌─────────────────────────────────────────────────┐
│                  Master Node                     │
│  - Tracks all slaves via MongoDB                │
│  - Distributes pasteboxes (load balancing)      │
│  - Monitors health (heartbeats)                 │
│  - Manages slave lifecycle (kick/remove)        │
│  - Raft consensus for leader election           │
└─────────────────────────────────────────────────┘
                      │
        ┌─────────────┼─────────────┐
        │             │             │
   ┌────▼───┐   ┌────▼───┐   ┌────▼───┐
   │ Slave 1│   │ Slave 2│   │ Slave 3│
   │ ─────  │   │ ─────  │   │ ─────  │
   │ Boxes  │   │ Boxes  │   │ Boxes  │
   │ Metrics│   │ Metrics│   │ Metrics│
   └────────┘   └────────┘   └────────┘
        │             │             │
        └─────────────┴─────────────┘
                      │
              ┌───────▼────────┐
              │    MongoDB     │
              │  - Nodes       │
              │  - Pasteboxes  │
              │  - Heartbeats  │
              └────────────────┘

Key Features

Automatic Load Balancing: Multiple placement strategies (LeastLoaded, RoundRobin, ResourceBased, Affinity)
Health Monitoring: Real-time heartbeat tracking with configurable timeouts
Node Management: Inspect, kick, or remove nodes via UI or API
Persistence: All cluster state stored in MongoDB for recovery
gRPC Communication: High-performance protocol buffers for cluster coordination
Raft Consensus: Leader election for master node high availability

Configuration

Master Node

cluster:
  enabled: true
  node_type: "master"
  heartbeat_interval: 10
  slave_timeout: 30

Slave Node

cluster:
  enabled: true
  node_type: "slave"
  master_url: "http://master-ip:8080"
  heartbeat_interval: 10

Cluster Management UI

The dashboard provides comprehensive cluster management:

Node List: View all active slaves with real-time metrics
Health Visualization: CPU, memory, disk usage per node
Pastebox Distribution: See which boxes are on which nodes
Node Inspection: Drill down into individual nodes to view their pasteboxes
Administrative Actions: Kick unhealthy nodes, remove dead nodes

🌐 Web Dashboard

Modern React-based dashboard with Redux state management and real-time updates.

Features

Pastebox Management - Create, view, delete pasteboxes
Unified File Explorer - Files, Pastes, and Secrets in one place
Real-time Monitoring - CPU, memory, disk usage charts (Recharts)
Monaco Code Editor - Syntax-highlighted paste creation/viewing
Custom Dialogs - Modern modal dialogs for all interactions
Per-Box Logging - Detailed operation logs for each pastebox
Cluster Dashboard - Multi-node visualization and management
Node Inspection - Per-node pastebox listing and metrics

Creating a Pastebox

Navigate to http://localhost:5173
Click "Create Pastebox"
Configure:
- TTL - Time to live (seconds)
- Max Storage - Storage limit in MB
- Encryption - Enable/disable encryption
Click "Create"

File Explorer

The unified file explorer manages:

📁 Files - Upload, download, encrypt/decrypt
📝 Pastes - Code snippets with syntax highlighting
🔑 Secrets - Key-value encrypted storage

Cluster Management

Navigate to the Cluster tab to:

View all registered nodes
Monitor node health in real-time
Inspect pasteboxes on specific nodes
Kick or remove unhealthy nodes
View cluster-wide statistics

🖥️ SSH/SFTP Access

Each pastebox has its own SSH shell and SFTP access with flexible authentication options.

Authentication Methods

Method	Description
Password	Auto-generated secure password displayed on creation
Public Key	ED25519, RSA, or ECDSA keys (like GitHub)
Both	Accept either password or public key

Connecting

# SSH Shell (password shown at creation)
ssh <box-id>@localhost -p 2222

# SSH with public key
ssh -i ~/.ssh/id_ed25519 <box-id>@localhost -p 2222

# SFTP File Transfer
sftp -P 2222 <box-id>@localhost

SSH Shell Commands

Navigation

ls [-la]        # List files (-l=long format, -a=show hidden)
cd <path>       # Change directory
pwd             # Print current directory
tree [path]     # Show directory tree
find <pattern>  # Find files by name

File Operations

cat <file>      # Display file contents
head <file>     # Show first 10 lines
tail <file>     # Show last 10 lines
touch <file>    # Create empty file
mkdir <dir>     # Create directory
rm <path>       # Delete file or directory
mv <src> <dst>  # Move/rename file
cp <src> <dst>  # Copy file

Encryption

encrypt <file> <passphrase>      # Encrypt file → .pbx
decrypt <file.pbx> <passphrase>  # Decrypt file

Pastes

paste list                       # List all pastes
paste view <name> <passphrase>   # View paste contents

Secrets

secret list                              # List secret keys
secret set <key> <value> <passphrase>    # Store encrypted secret
secret get <key> <passphrase>            # Retrieve secret

Utility

info            # Show pastebox information
df              # Show disk usage
date            # Show current date/time
clear           # Clear screen
exit            # Close connection

SFTP Commands

put <local>           # Upload file
get <remote>          # Download file
put -r <folder>/      # Upload folder recursively
get -r <folder>/      # Download folder recursively
ls, cd, pwd, mkdir, rm, rename

🔐 Encryption System

Zero-Knowledge Architecture

Passphrases never stored on server
All encryption/decryption client-side or in isolated containers
Only encrypted data stored on disk

Cipher Algorithms

Algorithm	Description	Use Case
ChaCha20-Poly1305 ⭐	Default, fast & secure	General files
XChaCha20-Poly1305	Extended nonce	Large datasets
AES-256-GCM	Hardware accelerated	Intel/AMD systems
AES-256-SIV	Misuse-resistant	Critical data

Key Derivation Functions

KDF	Description	Security Level
Argon2id ⭐	PHC winner	Highest
scrypt	Memory-hard	High
PBKDF2	NIST approved	Compatible

Encrypted File Format (.pbx)

┌────────────────────────────────────┐
│ Magic: "PBX\x00" (4 bytes)         │
│ Version: 2 (2 bytes)               │
│ Cipher Algorithm (1 byte)          │
│ KDF Algorithm (1 byte)             │
│ Nonce (12-24 bytes)                │
│ Salt (16-32 bytes)                 │
│ Metadata (encrypted JSON)          │
│ Content (encrypted)                │
│ Auth Tag (16 bytes)                │
└────────────────────────────────────┘

Usage Examples

Web UI

Upload file with passphrase → stored as .pbx
Download encrypted file → enter passphrase → decrypted download

SSH

# Encrypt
encrypt document.pdf mysecretpass

# Decrypt
decrypt document.pdf.pbx mysecretpass

API

# Upload encrypted
curl -X POST "http://localhost:8080/api/pastebox/BOX_ID/files/upload" \
  -F "[email protected]" \
  -F "path=/" \
  -F "passphrase=mysecretpass"

# Decrypt
curl -X POST "http://localhost:8080/api/pastebox/BOX_ID/files/decrypt" \
  -d '{"path": "/document.pdf.pbx", "passphrase": "mysecretpass"}'

🐳 Native Virtualization

Overview

Pastebox uses native OS primitives for containerization - no Docker required.

Platform	Technology
Linux	cgroups v2 + namespaces
macOS	sandbox-exec profiles

Resource Limits

Each pastebox can have configurable limits:

container:
  enabled: true
  limits:
    memory_mb: 512      # Memory limit
    cpu_quota_micros: 100000
    cpu_period_micros: 100000
    pids_limit: 100     # Max processes

Isolation Features

Filesystem - Isolated storage per box
Process - Separate PID namespace (Linux)
Network - Optional network isolation
Resources - CPU/memory quotas enforced by OS

Platform-Specific Implementation

Linux (cgroups v2)

Full namespace isolation (PID, Mount, Network, UTS, IPC)
cgroups v2 for resource limiting
Unified hierarchy for all controllers

macOS (sandbox-exec)

Sandbox profiles for filesystem restrictions
Process-level resource monitoring
Compatible with macOS security model

💾 Persistence & Recovery

Dual-Layer Storage Strategy

Layer	Component	Storage Location	Data Type
Metadata Layer	MongoDB	`pasteboxes` collection	Box settings, TTL, owner, encryption status
Object Layer	Filesystem	`data/storage/{boxID}/`	Files, pastes, secrets, logs

MongoDB Collections

`pasteboxes`

Stores all pastebox metadata:

{
  "id": "box-123",
  "owner_id": "guest",
  "assigned_node": "slave-abc123",
  "created_at": "2026-01-04T18:00:00Z",
  "expires_at": "2026-01-04T19:00:00Z",
  "status": "active",
  "max_size_mb": 500,
  "encryption_enabled": true
}

`cluster_nodes`

Tracks all cluster nodes:

{
  "node_id": "slave-abc123",
  "node_type": "slave",
  "host": "192.168.1.100",
  "port": 8080,
  "status": "active",
  "last_heartbeat": "2026-01-04T18:39:00Z",
  "cpu_usage": 45.2,
  "memory_usage": 60.1,
  "active_pasteboxes": 5
}

Automatic Instance Restoration

On daemon startup:

Database Discovery: Queries MongoDB for all active pasteboxes
Resource Rebuild: Re-registers instances with configured limits
Connectivity Restore: Re-opens channels and updates load balancer
Lifecycle Resumption: Restores boxes to their last known state

Connection Resilience

Exponential Backoff: 10 retries with 1s-30s delays
Health Checks: Pre-operation connection validation
Graceful Degradation: Continues operating for in-memory boxes if MongoDB is unavailable

☁️ Cloud Storage (S3/R2)

Pastebox supports S3-compatible cloud storage backends including AWS S3, Cloudflare R2, MinIO, and more. Cloud storage enables horizontal scaling across multiple nodes with shared storage.

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                       PASTEBOX                                   │
│                                                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           S3/R2 BUCKET (your-bucket/box-xxx)              │   │
│  └────────────────────────────┬─────────────────────────────┘   │
│                               │                                  │
│                        FUSE MOUNT (rclone)                       │
│                               │                                  │
│                               ▼                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │           /data/storage/box-xxx  (mounted)                │   │
│  │   • Terminal works normally ✅                            │   │
│  │   • Encryption before write ✅                            │   │
│  │   • All data stored in cloud ✅                           │   │
│  └──────────────────────────────────────────────────────────┘   │
│                               │                                  │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                  SANDBOXED SHELL                          │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

Configuration

When creating a pastebox via API:

{
  "userId": "alice",
  "storageBackend": "s3",
  "s3Config": {
    "bucket": "my-pastebox-bucket",
    "accessKeyId": "AKIAXXXXXXXX",
    "secretAccessKey": "secret-key",
    "endpoint": "https://s3.us-east-1.amazonaws.com",
    "region": "us-east-1"
  }
}

For Cloudflare R2:

{
  "storageBackend": "r2",
  "s3Config": {
    "bucket": "my-pastebox-bucket",
    "accessKeyId": "your-r2-access-key",
    "secretAccessKey": "your-r2-secret-key",
    "endpoint": "https://xxxx.r2.cloudflarestorage.com",
    "region": "auto"
  }
}

Security Features

Feature	Description
Credential Encryption	S3 secret keys encrypted with XChaCha20-Poly1305 at rest
Secure Mount	Credentials exist only during mount, then securely deleted
Zero-Knowledge	Config files zero-wiped before deletion
Permission Lockdown	Temp config files use 0600 permissions
Mount Verification	Validates mount success before proceeding

Prerequisites

# macOS
brew install rclone

# Linux
apt install rclone

# Verify installation
rclone version

Lifecycle

Create Box → Credentials decrypted → Mount S3 → Create sandbox
Use Terminal → Files read/written transparently to cloud
Kill Box → Unmount S3 → Cleanup mount point

📡 API Reference

Authentication

POST /api/auth/token
Content-Type: application/json

{"user_id": "alice"}

Response:

{"token": "eyJhbGciOiJIUzI1NiIs..."}

Pastebox Management

Create Pastebox

POST /api/pastebox/create
Authorization: Bearer <token>

{
  "encryption": true,
  "ttl": 3600,
  "max_size_mb": 500,
  "storageBackend": "s3",
  "languages": ["python", "node"],
  "sshAuthMethods": ["password", "publickey"],
  "sshPublicKeys": [
    {
      "name": "My Laptop",
      "publicKey": "ssh-ed25519 AAAA... [email protected]"
    }
  ],
  "s3Config": {
    "bucket": "my-pastebox-bucket",
    "accessKeyId": "AKIAIOSFODNN7EXAMPLE",
    "secretAccessKey": "wJalrXUtnFEMI...",
    "endpoint": "https://s3.amazonaws.com",
    "region": "us-east-1"
  }
}

Response includes SSH credentials:

{
  "id": "box-abc123",
  "sshPassword": "XyZ123SecurePass",
  "sshAuthMethods": ["password", "publickey"],
  "sshPublicKeys": [{"fingerprint": "SHA256:...", "keyType": "ed25519"}]
}

Field	Type	Description
`storageBackend`	string	`local`, `s3`, or `r2`
`sshAuthMethods`	string[]	`password`, `publickey`, or both
`sshPublicKeys`	object[]	SSH public keys with name and content
`languages`	string[]	Runtimes: `python`, `node`, `go`, `rust`, `c`, `ruby`, `php`, `bash`
`s3Config`	object	Required for S3/R2 storage (credentials encrypted before storage)

List Pasteboxes

GET /api/pastebox/list
Authorization: Bearer <token>

Get Details

GET /api/pastebox/<box_id>/details
Authorization: Bearer <token>

Delete Pastebox

DELETE /api/pastebox/<box_id>
Authorization: Bearer <token>

File Operations

List Files

GET /api/pastebox/<box_id>/files?path=/

Upload File

POST /api/pastebox/<box_id>/files/upload
Content-Type: multipart/form-data

file: <binary>
path: /
passphrase: optional

Download/Decrypt

POST /api/pastebox/<box_id>/files/decrypt

{
  "path": "/document.pdf.pbx",
  "passphrase": "secret"
}

Cluster Management

List Nodes

GET /api/cluster/nodes
Authorization: Bearer <token>

Inspect Node

GET /api/cluster/nodes/<node_id>
Authorization: Bearer <token>

Kick Node

POST /api/cluster/nodes/<node_id>/kick
Authorization: Bearer <token>

Get Node Pasteboxes

GET /api/cluster/nodes/<node_id>/pasteboxes
Authorization: Bearer <token>

Health & Metrics

GET /api/metrics/health
GET /api/metrics/system
GET /api/cluster/stats

💻 CLI Commands

pasteboxctl

# Build CLI
go build -o pasteboxctl ./cmd/pasteboxctl

# Authentication
pasteboxctl auth --user alice

# Create Pastebox (basic)
pasteboxctl create --ttl 3600 --encrypt

# Create with local storage and language runtimes
pasteboxctl create --storage local --languages python,node,go

# Create with AWS S3 storage
pasteboxctl create --storage s3 --s3-bucket mybucket \
  --s3-access-key AKIAIOSFODNN7EXAMPLE \
  --s3-secret-key wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY \
  --s3-region us-east-1

# Create with Cloudflare R2 storage
pasteboxctl create --storage r2 --s3-bucket mybucket \
  --s3-endpoint https://xxx.r2.cloudflarestorage.com \
  --s3-access-key ... --s3-secret-key ...

# Management
pasteboxctl list
pasteboxctl status <box_id>
pasteboxctl kill <box_id>

Create Command Flags

Flag	Description
`--ssh-auth`	Auth method: `password`, `publickey`, or `both`
`--ssh-public-key`	SSH public key content for key auth
`--ssh-key-name`	Name for the SSH key
`--storage`	Storage backend: `local`, `s3`, `r2`
`--languages`	Runtimes: `python,node,go,rust,c,ruby,php,bash`
`--s3-bucket`	S3/R2 bucket name
`--s3-access-key`	Access key ID
`--s3-secret-key`	Secret access key (encrypted before storage)
`--s3-endpoint`	R2 endpoint URL (required for Cloudflare)
`--s3-region`	AWS region or `auto` for R2

Paste Commands

# Pastes
pasteboxctl paste create --box <id> --name "config" --content "..."
pasteboxctl paste list --box <id>
pasteboxctl paste get --box <id> --name "config" -p "passphrase"

# Secrets
pasteboxctl secrets set --box <id> --key "API_KEY" --value "xxx" -p "pass"
pasteboxctl secrets list --box <id>
pasteboxctl secrets get --box <id> -p "pass"

# Cluster
pasteboxctl cluster nodes
pasteboxctl cluster inspect <node_id>
pasteboxctl cluster kick <node_id>

# Health
pasteboxctl health

# Files & Logs
pasteboxctl files <box_id>       # List files in pastebox
pasteboxctl logs <box_id>        # Show pastebox logs
pasteboxctl engine-logs          # Show global engine logs
pasteboxctl engine-logs -n 100   # Show last 100 log entries

# API Tokens
pasteboxctl token generate -n "CLI Token"  # Generate new token
pasteboxctl token list                      # List all tokens
pasteboxctl token revoke <token_id>         # Revoke a token

🔑 API Tokens

Generate API tokens for CLI and programmatic access:

From Web UI:

Go to Dashboard > API Access Tokens
Enter a name for your token
Click "Generate"
Copy the token immediately - it won't be shown again!

From CLI:

# Generate a new token
pasteboxctl token generate -n "My CLI Token"

# Use the token
export PASTEBOX_TOKEN="pb_abc123..."
pasteboxctl list

Using Tokens:

# Environment variable (recommended)
export PASTEBOX_TOKEN="pb_abc123..."
pasteboxctl list

# Command flag
pasteboxctl list --token "pb_abc123..."

# With curl
curl -H "Authorization: Bearer pb_abc123..." \
  http://localhost:8080/api/pasteboxes

⚙️ Configuration

config.yaml

server:
  port: 8080
  ssh_port: 2222
  host: "0.0.0.0"

mongodb:
  uri: "mongodb://localhost:27017"
  database_prefix: "pastebox_"

storage:
  base_path: "./data/storage"
  max_box_size_mb: 1000
  backend: "local"  # "local", "s3", or "r2"
  
  # S3/R2 Configuration (only if backend is "s3" or "r2")
  s3:
    bucket: "my-pastebox-bucket"
    access_key_id: ""      # Or use PASTEBOX_S3_ACCESS_KEY env var
    secret_access_key: ""  # Or use PASTEBOX_S3_SECRET_KEY env var  
    endpoint: ""           # Required for R2: https://xxx.r2.cloudflarestorage.com
    region: "us-east-1"    # Use "auto" for R2

container:
  enabled: true
  mode: "native"
  base_path: "./data/containers"
  limits:
    memory_mb: 512
    cpu_quota_micros: 100000
    cpu_period_micros: 100000
    pids_limit: 100
  namespaces:
    pid: true
    mount: true
    network: true
    uts: true
    ipc: true
    user: false

daemon:
  max_instances: 100
  health_check_interval: 30s
  instance_timeout: 10m

cluster:
  enabled: true
  node_type: "master"  # or "slave"
  master_url: ""       # Required for slaves
  heartbeat_interval: 10
  slave_timeout: 30

encryption:
  algorithm: "AES-256-GCM"
  key_iterations: 100000

logging:
  level: "info"
  format: "json"

jwt:
  secret: "your-secret-key"
  expiry_hours: 24

Environment Variables

Variable	Description
`PASTEBOX_CONFIG`	Path to config file
`PASTEBOX_JWT_SECRET`	JWT signing secret
`PASTEBOX_STORAGE_PATH`	Storage directory
`PASTEBOX_CREDENTIAL_KEY`	Master key for encrypting S3/R2 secrets (32 bytes hex)
`MONGODB_URI`	MongoDB connection string
`PASTEBOX_S3_ACCESS_KEY`	S3/R2 access key (overrides config)
`PASTEBOX_S3_SECRET_KEY`	S3/R2 secret key (overrides config)

🚀 Deployment

Terraform (Infrastructure as Code)

Terraform configurations are provided for multiple cloud platforms:

hosting/terraform/
├── main.tf           # Render.com (simple PaaS)
├── aws/
│   └── main.tf       # AWS ECS Fargate + ALB
└── cloudflare/
    └── main.tf       # Cloudflare R2 + WAF

Deploy to Render.com

cd hosting/terraform
cp terraform.tfvars.example terraform.tfvars
# Edit terraform.tfvars with your values
terraform init && terraform apply

Deploy to AWS

cd hosting/terraform/aws
terraform init && terraform apply
# Creates: ECS Fargate, ECR, ALB, VPC, autoscaling (2-10 instances)

Cloudflare R2 + WAF

cd hosting/terraform/cloudflare
terraform init && terraform apply
# Creates: R2 bucket, WAF rules, rate limiting, caching

Docker

🚀 Deployment

Option 1: Docker (Recommended for Production)

# Clone and start with Docker Compose
git clone https://github.com/pastezen/pastebox.git
cd pastebox

# Start all services (pastebox + mongodb)
docker-compose up -d

# View logs
docker-compose logs -f pastebox

Access:

Web Dashboard: http://localhost:8080
SSH/SFTP: ssh box-xxx@localhost -p 2222

Environment Variables:

# Set encryption key for S3 credentials (optional but recommended)
export PASTEBOX_CREDENTIAL_KEY="your-32-byte-key-here"
docker-compose up -d

Option 2: Linux Server (Ubuntu/Debian)

# Clone repository
git clone https://github.com/pastezen/pastebox.git
cd pastebox

# Run setup script (installs Go, Node, MongoDB, rclone, FUSE)
chmod +x scripts/setup-linux.sh
sudo ./scripts/setup-linux.sh

# Start with systemd
sudo systemctl start pastebox
sudo systemctl enable pastebox  # Auto-start on boot

# Check status
sudo systemctl status pastebox

Option 3: macOS (Development)

# Clone repository
git clone https://github.com/pastezen/pastebox.git
cd pastebox

# Run setup script (installs Homebrew, Go, Node, MongoDB, macFUSE, rclone)
chmod +x scripts/setup-macos.sh
./scripts/setup-macos.sh

# ⚠️ After macFUSE install: Restart Mac and approve kernel extension
# System Settings → Privacy & Security → Allow

# Start MongoDB
brew services start mongodb-community

# Start Pastebox
./router

Manual Docker Build

docker build -t pastebox .
docker run -d \
  --name pastebox \
  --privileged \
  --device /dev/fuse \
  -p 8080:8080 \
  -p 2222:2222 \
  -v pastebox-data:/app/data/storage \
  pastebox

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│                     Routing Daemon (Go)                      │
├─────────────────┬─────────────────┬─────────────────────────┤
│   HTTP API      │   SSH Gateway   │   Cluster Manager       │
│   (Port 8080)   │   (Port 2222)   │   (gRPC + REST)         │
└────────┬────────┴────────┬────────┴────────┬────────────────┘
         │                 │                 │
    ┌────▼────┐       ┌────▼────┐       ┌────▼────┐
    │ Box #1  │       │ Box #2  │       │ Box #3  │
    │ ─────── │       │ ─────── │       │ ─────── │
    │ Storage │       │ Storage │       │ Storage │
    │ Limits  │       │ Limits  │       │ Limits  │
    │ Metrics │       │ Metrics │       │ Metrics │
    └─────────┘       └─────────┘       └─────────┘
         │                 │                 │
         └─────────────────┴─────────────────┘
                           │
                   ┌───────▼────────┐
                   │    MongoDB     │
                   │  - Pasteboxes  │
                   │  - Nodes       │
                   │  - Events      │
                   └────────────────┘

Directory Structure

pastebox/
├── cmd/
│   ├── router/          # Main daemon
│   └── pasteboxctl/     # CLI tool
├── client/              # React dashboard (Vite + TypeScript)
│   ├── src/
│   │   ├── features/    # Feature modules (cluster, files, etc.)
│   │   ├── store/       # Redux store and slices
│   │   └── lib/         # API client and utilities
│   └── package.json
├── internal/
│   ├── cluster/         # Master/slave coordination
│   ├── container/       # Native virtualization
│   ├── daemon/          # Core pastebox logic
│   ├── database/        # MongoDB repositories
│   ├── encryption/      # Crypto operations
│   └── gateway/         # SSH/SFTP servers
├── pkg/
│   ├── config/          # Configuration management
│   └── logger/          # Structured logging
└── data/
    ├── storage/         # Pastebox file storage
    ├── containers/      # Container runtime data
    └── mongodb/         # MongoDB data directory

Technology Stack

Backend

Language: Go 1.21+
Database: MongoDB 7.0+
Cache: Redis (optional)
Protocols: HTTP/REST, gRPC, SSH, SFTP
Consensus: Raft (for master election)

Frontend

Framework: React 19
Build Tool: Vite 7
State Management: Redux Toolkit
UI Components: Custom + Radix UI
Charts: Recharts
Code Editor: Monaco Editor
Styling: TailwindCSS + Framer Motion

🔒 Security

Encryption

All sensitive data encrypted with ChaCha20-Poly1305 or AES-256-GCM
Argon2id for key derivation (memory-hard, resistant to GPU attacks)
Zero-knowledge architecture (server never sees passphrases)
Authenticated encryption with associated data (AEAD)

Isolation

Each pastebox runs in isolated container (cgroups/sandbox)
Resource limits prevent DoS attacks
Filesystem isolation prevents cross-box access
Process namespace isolation (Linux)

Authentication

JWT-based API authentication with configurable expiry
SSH key and password authentication
Rate limiting on all endpoints
CORS protection with configurable origins

Network Security

TLS/SSL support for production deployments
Configurable firewall rules per container
Network namespace isolation (Linux)
Secure gRPC communication for cluster

📊 Monitoring & Observability

Real-Time Metrics

System-Level: CPU, memory, disk, network
Node-Level: Per-slave resource utilization
Box-Level: Storage usage, file counts, operation logs

Health Checks

Automatic heartbeat monitoring
Configurable timeout thresholds
Dead node detection and removal
Cluster-wide health aggregation

Logging

Structured JSON logging
Per-box operation logs
Cluster event tracking
Configurable log levels (debug, info, warn, error)

⚡ Code Execution API

Run code in isolated sandboxes via HTTP API:

# Execute Python code
curl -X POST http://localhost:8080/api/execute \
  -H "Content-Type: application/json" \
  -d '{
    "language": "python",
    "code": "print(\"Hello from Pastebox!\")",
    "timeout": 10
  }'

# Response
{
  "success": true,
  "stdout": "Hello from Pastebox!\n",
  "stderr": "",
  "exitCode": 0,
  "executionTime": 0.045
}

Supported Languages

Language	Command	Extension
Python	`python3`	.py
JavaScript	`node`	.js
Go	`go run`	.go
Rust	`rustc`	.rs
C	`gcc`	.c
C++	`g++`	.cpp
Ruby	`ruby`	.rb
PHP	`php`	.php
Bash	`bash`	.sh

Per-Box Isolated Runtimes

Each pastebox can have its own language installations:

// Provision a box with specific languages
runtime.ProvisionBox("box-123", []string{"python", "node", "go"})

// Execute code in the box's isolated environment
result := runtime.ExecuteInBox(ctx, "box-123", ExecuteRequest{
    Language: "python",
    Code: "import sys; print(sys.version)",
})

🖥️ WebSocket Terminal

Browser-based shell access that works on any cloud platform (no SSH port required):

Frontend Usage (React + xterm.js)

import { Terminal } from '@xterm/xterm';

const ws = new WebSocket('wss://pastebox.com/api/pastebox/box-123/terminal');

// Send input
ws.send(JSON.stringify({ type: 'input', data: 'ls -la\n' }));

// Receive output
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === 'output') {
    terminal.write(msg.data);
  }
};

// Resize terminal
ws.send(JSON.stringify({ type: 'resize', cols: 120, rows: 40 }));

Message Protocol

Type	Direction	Description
`input`	Client → Server	Keyboard input
`output`	Server → Client	Shell output
`resize`	Client → Server	Terminal resize (cols, rows)
`error`	Server → Client	Error message

☁️ Cloud Storage (S3/R2)

Enable horizontal scaling with S3-compatible storage:

# config.yaml
storage:
  backend: "s3"  # "local" or "s3"
  s3:
    endpoint: "https://xxx.r2.cloudflarestorage.com"  # Cloudflare R2
    bucket: "pastebox-storage"
    access_key_id: "${S3_ACCESS_KEY_ID}"
    secret_access_key: "${S3_SECRET_ACCESS_KEY}"
    region: "auto"

Benefits of Cloud Storage

Feature	Local Storage	S3/R2 Storage
Horizontal Scaling	❌ Single instance	✅ Unlimited
Data Durability	⚠️ Single disk	✅ 11 9's
Size Limit	Limited by disk	✅ Unlimited
Cost	Fixed	Pay per GB

🛡️ Security Hardening

Four security levels for different use cases:

Level	Memory	CPU	Network	Use Case
Minimal	1 GB	2 CPU	Full	Testing
Standard	512 MB	1 CPU	Loopback	Production
Strict	256 MB	0.5 CPU	Disabled	High Security
Paranoid	128 MB	0.25 CPU	Disabled	Maximum Security

Security Features

seccomp: 70+ allowed syscalls, kill on violation
Capabilities: Drop ALL (CAP_SYS_ADMIN, etc.)
Namespaces: PID, Mount, Network, User, IPC, UTS, Cgroup, Time
cgroups v2: Memory, CPU, PIDs, I/O limits
Filesystem: Read-only root, masked paths, no-exec /tmp
Flags: NO_NEW_PRIVS, no ptrace, no core dumps, rootless

🚀 Production Deployment

Recommended Setup

MongoDB Replica Set: For high availability
Load Balancer: Nginx or HAProxy in front of master nodes
TLS Termination: Use Let's Encrypt for HTTPS
Monitoring: Prometheus + Grafana for metrics
Backup: Regular MongoDB backups and storage snapshots

Scaling Strategy

Horizontal: Add more slave nodes for capacity
Vertical: Increase resources per node for larger boxes
Geographic: Deploy slaves in different regions for latency

📄 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions welcome! Please read our contributing guidelines.

🔗 Links

Documentation: docs/
API Spec: docs/api.md
Architecture: docs/architecture.md
Cluster Guide: docs/cluster.md

Built with ❤️ using Go, React, and MongoDB

Name		Name	Last commit message	Last commit date
client		client
cmd		cmd
docs		docs
hosting		hosting
internal		internal
pkg		pkg
scripts		scripts
tests		tests
.gitignore		.gitignore
Dockerfile		Dockerfile
Makefile		Makefile
README.md		README.md
config.production.yaml		config.production.yaml
config.yaml		config.yaml
demo.sh		demo.sh
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
inspect_box.go		inspect_box.go

Uh oh!

Latest commit

History

Folders and files

Repository files navigation

🔐 Pastebox Engine

🌟 Features at a Glance

📚 Table of Contents

🚀 Quick Start

Prerequisites

Installation (Production)

Development Setup

First Run Checklist

Access Points

Troubleshooting

🌐 Cluster Architecture

Architecture Overview

Key Features

Configuration

Master Node

Slave Node

Cluster Management UI

🌐 Web Dashboard

Features

Creating a Pastebox

File Explorer

Cluster Management

🖥️ SSH/SFTP Access

Authentication Methods

Connecting

SSH Shell Commands

Navigation

File Operations

Encryption

Pastes

Secrets

Utility

SFTP Commands

🔐 Encryption System

Zero-Knowledge Architecture

Cipher Algorithms

Key Derivation Functions

Encrypted File Format (.pbx)

Usage Examples

Web UI

SSH

API

🐳 Native Virtualization

Overview

Resource Limits

Isolation Features

Platform-Specific Implementation

Linux (cgroups v2)

macOS (sandbox-exec)

💾 Persistence & Recovery

Dual-Layer Storage Strategy

MongoDB Collections

pasteboxes

cluster_nodes

Automatic Instance Restoration

Connection Resilience

☁️ Cloud Storage (S3/R2)

How It Works

Configuration

Security Features

Prerequisites

Lifecycle

📡 API Reference

Authentication

Pastebox Management

Create Pastebox

List Pasteboxes

Get Details

Delete Pastebox

File Operations

List Files

Upload File

Download/Decrypt

Cluster Management

List Nodes

`pasteboxes`

`cluster_nodes`