Scratchbox

Scratchbox is a minimal self-hosted scratch service written in Go. It is intentionally unauthenticated and optimized for temporary sharing of text or small files with an expiration time.

Each upload creates exactly one scratch. For multi-file sharing, bundle files into an archive (for example .zip or .tar.gz) and upload that single archive file. Scratch content is stored on disk gzip-compressed transparently to reduce filesystem usage; API/UI reads return original uncompressed content.

Quick Start

1. Generate defaults directly:
   • go run ./cmd/scratchbox generate-config > config.yaml
2. Adjust settings for your environment.
3. Start the server:
   • go run ./cmd/scratchbox server --config config.yaml
4. Open:
   • http://127.0.0.1:8080/

Without --config, built-in defaults are used.

If you modify the web UI source (web/ui), rebuild frontend assets with:

• make build

Configuration

All configuration is YAML.

server

• listen_addr: address for the HTTP server (required).
  • Default: :8080
• read_header_timeout: maximum time for reading request headers.
  • Must be > 0
  • Default: 5s
• read_timeout: maximum time for reading the full request.
  • Must be > 0
  • Default: 30s
• write_timeout: maximum time allowed for writing the response.
  • Must be > 0
  • Default: 30s
• idle_timeout: maximum keep-alive idle time between requests.
  • Must be > 0
  • Default: 120s
• max_header_bytes: max HTTP header size in bytes.
  • Must be > 0
  • Default: 1048576 (1 MiB)

limits

• max_upload_size: max request body size for uploads.
  • Supported units: B, KB, MB, GB, KiB, MiB, GiB (case-insensitive)
  • If no unit is provided, value is interpreted as bytes
  • Examples: 5MB, 100MiB, 1GiB, 1048576
  • Default: 100MiB
• default_ttl: expiration applied to new scratches.
  • Must be > 0 and <= 24h
  • Default: 1h
• raw_cache_max_size: max total decompressed bytes cached in memory for /api/raw range requests.
  • Supported units: B, KB, MB, GB, KiB, MiB, GiB (case-insensitive)
  • Must be > 0
  • Default: 200MiB
• raw_cache_max_entries: max number of decompressed /api/raw entries kept in memory.
  • Must be > 0
  • Used together with raw_cache_max_size as a secondary cap
  • Default: 32

storage

• data_dir: directory for scratch files and metadata index.
  • Default: ./data
• cleanup_interval: background interval for deleting expired content.
  • Must be at least 10s
  • Default: 1m

security

• allowed_ips: optional list of IPs and CIDRs allowed to create scratches.
  • Applies to write route only: POST /api/scratch
  • Default includes 127.0.0.1 (localhost-only write access)
  • Add trusted IPs/CIDRs for LAN/proxy clients (for example 192.168.1.0/24)
  • Empty list means no allowlist restriction
• trust_proxy_headers: if true, client IP extraction honors X-Forwarded-For then X-Real-IP.
  • Only used when source IP matches trusted_proxy_ips.
  • Keep false unless behind a trusted reverse proxy that sets these headers.
• trusted_proxy_ips: list of reverse-proxy IPs/CIDRs permitted to supply forwarded headers.
  • Required when trust_proxy_headers: true
  • Examples: 127.0.0.1, 10.0.0.0/8
• rate_limit.enabled: enable per-IP token-bucket rate limiting on write route.
  • Default: true
• rate_limit.requests_per_minute: steady refill rate per client IP.
  • Must be > 0
  • Default: 30
• rate_limit.burst: immediate burst capacity per client IP.
  • Must be > 0
  • Default: 10

Security Posture

This service is intentionally unauthenticated. Anyone with network access can read scratches, and (unless restricted) create scratches.

• No authentication, user accounts, or moderation controls.
• No malware scanning.
• Abuse controls are limited to upload size limits, TTL expiration, optional IP allowlisting, and write-route rate limiting.
• Treat this as a convenience utility, not a hardened internet-facing platform.

LAN Deployment Notes

For home/lab/LAN-only use:

• Bind to a private address, for example 127.0.0.1:8080 (single host) or 192.168.x.x:8080.
• Use allowed_ips to restrict write access to trusted subnets.
• Keep max_upload_size and default_ttl small.
• Keep trust_proxy_headers disabled unless using a trusted reverse proxy.

Public Deployment Notes

If exposed beyond a trusted LAN, place a reverse proxy in front (Nginx, Caddy, Traefik, etc.) and add external controls:

• TLS termination and strict transport settings.
• Additional request filtering/WAF controls.
• Stronger rate limits at the edge.
• Optional network-level restrictions to write route.
• Monitoring and log retention suitable for abuse triage.

Recommended baseline: run behind a reverse proxy, keep low TTL and size limits, and use allowed_ips for write access whenever possible.

Storage Model

Scratchbox storage is designed for a single process instance per storage.data_dir.

• Do not run multiple scratchbox processes against the same data directory.
• Metadata/index writes are process-local and are not coordinated with cross-process locking.