Octa — High-Performance Image Delivery Engine

Why we built Octa.

Handling user identities and lightweight assets shouldn't require complex cloud infrastructure. Octa is the specialized alternative.

Faster than Filesystem

Research shows SQLite reads small blobs (like avatars) 35% faster than the filesystem. Octa leverages WAL mode for high-performance I/O without lock contention.

Not another S3 bucket

Stop managing IAM roles and egress fees for 50KB files. Octa replaces complex object storage with a simple, portable single-file architecture.

Single Binary Deploy

No external dependencies. No Redis or PostgreSQL required. The database, cache, image transformer, and server are compiled into one lightweight executable.

Read the full architectural deep dive

Configuration

Octa is designed to be "Zero-Config" by default, but highly tunable via `config.yaml`. Every setting can also be overridden using environment variables (e.g., `OCTA_DATABASE_MAX_SIZE`), making it cloud-native ready.

1

Storage & Dual SQLite Quota

Define the SQLite database path and global quota (`storage.max_total_size`). Micro-assets reside in SQLite BLOBs while larger files automatically offload to disk.

2

Security & UnixID Personal SSO

Set `upload_secret` for write operations. Configure `unixid.api_url` to enable passwordless 6-digit TOTP personal login for administrators.

3

Embedded Management Console

Enable `consoleui` to inspect asset metadata, test on-the-fly transformations, review real-time audit logs, and trigger Rust forensic scans.

config.yaml

app:
  name: "Octa"
  version: "1.0-beta"

base_url: "https://octa.trymagic.xyz"

server:
  port: 9980
  env: "production" # development | production

storage:
  # Maximum storage quota (SQLite BLOBs + Disk Blobs)
  max_total_size: "10GB"

database:
  path: "./data/octa.db"
  max_size: "5GB"      
  prune_interval: "30m"

image:
  default_size: 360
  quality: 80
  max_upload_size: "10MB"
  max_key_limit: 7

cache:
  enabled: true
  max_capacity: 100 # MB
  ttl: "30m"

security:
  upload_secret: "YOUR_MASTER_SECRET_KEY"
  cors_origins:
    - "https://trymagic.xyz"
    - "https://*.trymagic.xyz"

  rate_limit:
    enabled: true
    requests: 50   # Req/sec per IP
    burst: 100     # Spike burst tolerance
    window: "1s"

consoleui:
  enabled: true    # Built-in management console
  user:
    username: "admin"
    password: "YourSecurePasswordHere"

unixid:
  # UnixID Personal SSO verification endpoint
  api_url: "https://api.unixid.roticeh.com"

API Reference

Simple, predictable REST endpoints to integrate Octa into any frontend or backend stack.

GET

/u/{key}

Unified Avatar Engine: Serves custom uploaded avatars if present, or automatically generates a crisp initials avatar on-the-fly.

Param	Type	Description
w, h	int	Width / Height dimensions (e.g. `256`)
format	string	Output codec: `webp`, `png`, `jpeg`
theme	string	Initials gradient palette (e.g. `gradient/pro`)

# Fetch avatar with automatic WebP conversion
curl "https://octa.trymagic.xyz/u/alex?w=256&format=webp"

# Force direct generator (bypassing DB)
curl "https://octa.trymagic.xyz/avatar/alex?theme=gradient/pro"

GET

/a/{key}

Strict Asset Delivery: Retrieves stored assets directly. Supports real-time Cengine transformations, Gaussian blur, rotation, and named presets.

# Fetch product image with preset
curl "https://octa.trymagic.xyz/a/products/shoe?preset=catalog_card"

# On-the-fly blur and format conversion
curl "https://octa.trymagic.xyz/a/brand/banner?w=1200&blur=5.0&format=webp"

POST

/upload

Uploads a media asset to the Hybrid Tiered Engine. Requires an authorized session cookie or Bearer API token. Supports multi-key aliasing.

Multi-Key Aliasing: Assign up to 7 distinct vanity keys (comma-separated) to a single asset without storage duplication.

curl -X POST https://octa.trymagic.xyz/upload \
  -H "Authorization: Bearer oct_live_secret_key" \
  -F "file=@profile.jpg" \
  -F "keys=users/alex,team/lead-dev" \
  -F "storage=sqlite"

The High-Performance SQLite-Native Asset Engine.