Kleo Static files

---

name: static-files description: > Host static files on subdomains with optional authentication. Use when you need to serve HTML, images, CSS, JS, or any static content on a dedicated subdomain. Supports file upload, basic auth, quota management, and automatic SSL via Caddy. Commands include sf sites (create/list/delete), sf upload (files/directories), sf files (list/delete).

---

Static Files Hosting

Host static content on *.{domain} subdomains with automatic SSL.

Quick Reference

# Create site
sf sites create mysite
→ https://mysite.498as.com
Upload file
sf upload ./index.html mysite
Upload directory  
sf upload ./dist mysite
Add authentication
sf sites auth mysite admin:secretpass123
List files
sf files mysite
Delete file
sf files mysite delete path/to/file.txt
Delete site
sf sites delete mysite

Environment Setup

export SF_API_URL=http://localhost:3000   # API endpoint
export SF_API_KEY=sk_xxxxx                # Your API key

Workflows

Deploy a Static Website

# 1. Create the site
sf sites create docs
2. Upload the build directory
sf upload ./build docs
3. Verify
curl -I https://docs.498as.com

Protected File Sharing

# 1. Create site with auth
sf sites create private
sf sites auth private user:strongpassword
2. Upload sensitive files
sf upload ./reports private
3. Share URL + credentials
https://private.498as.com (user / strongpassword)

Update Existing Files

# Overwrite existing file
sf upload ./new-version.pdf mysite --overwrite
Or delete and re-upload
sf files mysite delete old-file.pdf
sf upload ./new-file.pdf mysite

CLI Commands

sites

| Command | Description | |---------|-------------| | sf sites list | List all sites | | sf sites create | Create new site | | sf sites delete | Delete site and all files | | sf sites auth | Set basic auth | | sf sites auth --remove | Remove auth |

upload

sf upload   [subdir] [--overwrite] [--json]

path: File or directory to upload

site: Target site name

subdir: Optional subdirectory

--overwrite: Replace existing files

--json: Output JSON

files

| Command | Description | |---------|-------------| | sf files | List all files | | sf files delete | Delete specific file |

stats

sf stats              # Global stats
sf stats        # Site-specific stats

API Endpoints

Base: $SF_API_URL with Authorization: Bearer $SF_API_KEY

| Method | Path | Description | |--------|------|-------------| | GET | /sites | List sites | | POST | /sites | Create site | | DELETE | /sites/{name} | Delete site | | PATCH | /sites/{name} | Update auth | | GET | /sites/{name}/files | List files | | POST | /sites/{name}/files | Upload file | | DELETE | /sites/{name}/files/{path} | Delete file | | GET | /stats | Global stats | | GET | /stats/{name} | Site stats | | GET | /health | Health check |

Constraints

Site names: lowercase, alphanumeric, hyphens only (max 63 chars)

File size: 50MB default (configurable)

Quota: 100MB per site default

Rate limit: 100 requests/minute per API key

Troubleshooting

"Cannot connect to API"

# Check service status
systemctl status kleo-static-files
Check if port is listening
curl http://localhost:3000/health

"Invalid API key"

# Verify key is set
echo $SF_API_KEY
Create new key if needed
bun run /opt/kleo-static-files/scripts/create-key.ts "new-key"

"Quota exceeded"

# Check current usage
sf stats mysite
Delete unused files
sf files mysite delete large-file.zip

Site not accessible via HTTPS

# Verify DNS points to server
dig mysite.498as.com
Check Caddy config
cat /etc/caddy/sites.d/static-files.caddy
Resync Caddy
bun run /opt/kleo-static-files/scripts/sync-caddy.ts --reload

Installation

Server Installation (run once on host)

curl -fsSL https://raw.githubusercontent.com/498AS/kleo-static-files/main/install.sh | sudo bash

The installer outputs JSON with connection details between KLEO_SF_CONFIG_BEGIN and KLEO_SF_CONFIG_END markers. Parse this to get api_url and api_key.

After Installation

export SF_API_URL=http://localhost:3000
export SF_API_KEY=sk_xxxxx  # from installer output

Check Status

sudo /opt/kleo-static-files/install.sh --status

See references/install.md for manual installation.

"Cannot connect to API"

# Check service status
systemctl status kleo-static-files
Check if port is listening
curl http://localhost:3000/health

"Invalid API key"

# Verify key is set
echo $SF_API_KEY
Create new key if needed
bun run /opt/kleo-static-files/scripts/create-key.ts "new-key"

"Quota exceeded"

# Check current usage
sf stats mysite
Delete unused files
sf files mysite delete large-file.zip

Site not accessible via HTTPS

# Verify DNS points to server
dig mysite.498as.com
Check Caddy config
cat /etc/caddy/sites.d/static-files.caddy
Resync Caddy
bun run /opt/kleo-static-files/scripts/sync-caddy.ts --reload

Site names: lowercase, alphanumeric, hyphens only (max 63 chars)

File size: 50MB default (configurable)

Quota: 100MB per site default

Rate limit: 100 requests/minute per API key