Skip to content

Pastezen/Pastebox

Folders and files

NameName
Last commit message
Last commit date

Latest commit

Β 

History

3 Commits
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 
Β 

Repository files navigation

πŸ” 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.

Go Version React MongoDB License


🌟 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

πŸ“š Table of Contents


πŸš€ 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

  1. Navigate to http://localhost:5173
  2. Click "Create Pastebox"
  3. Configure:
    • TTL - Time to live (seconds)
    • Max Storage - Storage limit in MB
    • Encryption - Enable/disable encryption
  4. 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

  1. Upload file with passphrase β†’ stored as .pbx
  2. 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 "file=@document.pdf" \ -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:

  1. Database Discovery: Queries MongoDB for all active pasteboxes
  2. Resource Rebuild: Re-registers instances with configured limits
  3. Connectivity Restore: Re-opens channels and updates load balancer
  4. 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

  1. Create Box β†’ Credentials decrypted β†’ Mount S3 β†’ Create sandbox
  2. Use Terminal β†’ Files read/written transparently to cloud
  3. 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@example.com" } ], "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:

  1. Go to Dashboard > API Access Tokens
  2. Enter a name for your token
  3. Click "Generate"
  4. 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:

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

  1. MongoDB Replica Set: For high availability
  2. Load Balancer: Nginx or HAProxy in front of master nodes
  3. TLS Termination: Use Let's Encrypt for HTTPS
  4. Monitoring: Prometheus + Grafana for metrics
  5. 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


Built with ❀️ using Go, React, and MongoDB

About

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.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors