Octa — Specialized Asset Engine

Why we built Octa.

Handling user identities shouldn't require complex object storage 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.

Not another S3 bucket

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

Single Binary Deploy

No external dependencies. No Redis required. The database, the cache, and the server are all compiled into one lightweight executable.

Read the full architectural deep dive

Asset Playground

Test the deterministic generation engine in real-time.

Demo Mode: This playground attempts to connect to http://localhost:9980.
Ensure your local Octa instance is running to see generated avatars.

Seed Key

Style Engine

Palette

Format

Shape

Size

Override Background

Override Text Color

Force Initials

GET

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 & Pruning

Define the SQLite database path. Use `max_size` (e.g., "5GB") to enable auto-pruning. Octa will automatically delete the oldest assets when this threshold is reached, keeping disk usage predictable.

2

Security & Rate Limiting

`upload_secret` is mandatory for write operations. The built-in `rate_limit` uses a token bucket algorithm to protect public read endpoints from abuse (DDoS) without affecting legitimate users.

3

Management Console

Enable the embedded `consoleui` to visualize your asset library, monitor system health, and manually upload files via a web interface.

config.yaml

app:
  name: "Octa"
  version: "0.0.1"
  
base_url: "https://0.0.0.0:9980"
server:
  port: 9980
  env: "production" # development | production

database:
  path: "./data/octa.db"
  # Soft limit for auto-cleanup
  max_size: "5GB"      
  # How often to check size
  prune_interval: "10m"

image:
  # Base size for generated avatars
  default_size: 360
  # Reject uploads larger than this
  max_upload_size: "10MB"

  # Quality: Compression level for image output (1-100)
  quality: 80

  # MaxKeyLimit: Maximum number of aliases allowed for a single asset mapping (e.g., 7)
  max_key_limit: 7


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

security:
  # REQUIRED for /upload endpoint
  upload_secret: "YOUR_SECRET_KEY_HERE" # or use env
  cors_origins:
    - "http://localhost:9980" # accept only main
    - "https://**.example.com" # accept main and subdomains
    - "https://*.example2.com" # accept only subdomains

  rate_limit:
    enabled: true
    requests: 50   # Req/sec per IP
    burst: 100     # Allow traffic spikes
    window: "1s"

consoleui:
  enabled: true    # Access via http://localhost:9980/console
  user:
    username: "admin"
    password: "change_me" # Or use env var

API Reference

Simple endpoints to integrate Octa into your backend.

GET

/avatar/{seed}

Generates a deterministic avatar based on the seed (username, email, or uuid). Supports various formats and themes via query parameters.

Param	Type	Description
theme	string	style/palette (e.g. `gradient/retro`)
size	int	Output width in pixels (Default: 360)
rounded	bool	Apply circular mask (100 or 0)
format	string	Output format: `png` or `svg`

# Generate a gradient avatar
curl "{{.BaseURL}}/avatar/onur?theme=gradient/pro"

# Force SVG format
curl "{{.BaseURL}}/avatar/octa?format=svg"

POST

/upload

Uploads a static asset to the SQLite Blob store. Requires the X-Secret-Key header defined in your config.

Note: You can assign multiple alias keys (comma separated) to a single file.

curl -X POST {{.BaseURL}}/upload \
  -H "X-Secret-Key: YOUR_SECRET" \
  -F "file=@profile.jpg" \
  -F "keys=user-123,my-profile"

A focused engine for avatars and small assets.