Aeonic is an open-source, self-hosted media platform in active development. The intended product will provide storage, transformation, delivery, and optional media intelligence for individual developers and small teams.
Version 1.0.0-rc.2 is the hardened v1 release candidate. It combines optional semantic retrieval and approval-gated media workflows with reproducible performance, security, supply-chain, upgrade, rollback, and compatibility gates. It ships:
- A Node.js 24 and strict TypeScript 6 workspace.
- A contract-validated Express 5 API.
- Validated environment configuration.
- Structured JSON logging with credential redaction.
- Separate liveness and readiness endpoints.
- RFC 9457-compatible error responses.
- Automated lint, format, type, test, and build checks.
- SQLite persistence with reviewed Drizzle migrations and WAL-mode safety controls.
- Better Auth email/password sessions, organization roles, and organization-owned API-key support.
- A race-safe initial setup endpoint that atomically creates the first owner, organization, project, and audit event.
- Tenant-isolated project, membership, project API-key, and audit APIs.
- Tenant-scoped local and S3-compatible storage engines with immutable streaming writes.
- Streaming simple uploads with size limits, project quota reservations, optional SHA-256 checks, MIME/extension/signature validation, idempotent replay, and interrupted-upload reconciliation.
- Authenticated tus 1.0 resumable uploads with creation, expiry, SHA-1/SHA-256 chunk checksums, termination, durable offsets, and restart reconciliation.
- Immutable original-asset delivery over local or S3-compatible storage, including authenticated reads, expiring signed URLs, conditional requests, and single byte ranges.
- Project-scoped storage usage, quota, health, derivative-cache, and sanitized failure diagnostics.
- A standalone crash-safe worker that performs bounded image, video, PDF, and Office inspection before making an asset ready.
- A versioned, canonical image-transform grammar and an audited API for immutable named preset versions.
- Synchronous image transformation URLs with deterministic cache identities, single-flight generation, content negotiation, immutable validators, and signed private delivery.
- Durable asynchronous video posters, bounded clips and MP4/WebM transcodes, PDF thumbnails and text extraction, and Office-to-PDF previews.
- Tenant-scoped derivative status, authenticated delivery, explicit cache invalidation, retry-safe leases, processor versioning, and audited lifecycle events.
- OpenAPI 3.1 JSON at
/openapi.jsonand an interactive reference at/docs. - A responsive React dashboard for first-run setup, projects, uploads, asset metadata and privacy, presets, jobs, storage health, API keys, and audit history.
- A read-only
doctorcommand with configuration, SQLite, permission, and media-tool diagnostics. - A hardened three-service Docker Compose deployment with a Caddy TLS/static edge, internal API, internal worker, persistent data volumes, and operator backup/upgrade guidance.
- Optional hybrid lexical/vector media search with project isolation, privacy controls, budgets, evaluation gates, and a separately activated AI worker.
- Deterministic, exact-target agent plans with immutable hashes, administrator approval, single-use execution, cancellation, audit history, and worker-side revalidation.
- An optional project-scoped stdio MCP server whose mutation-capable tool can request human review but cannot approve or execute its own plan.
- Reproducible metadata, local-delivery, and image-transformation benchmarks; automated dependency and CodeQL checks; multi-architecture image builds with SBOM, provenance, vulnerability scanning, and keyless signatures; and an evidence-based release checklist.
AI and agent features remain explicitly optional. The API and worker must both be running for uploads to become ready and for queued derivatives or approved agent changes to complete.
- Node.js 24 LTS
- pnpm 11.25.0 through Corepack
- FFmpeg and ffprobe
- Poppler utilities (
pdfinfo,pdftotext, andpdftoppm) - LibreOffice for Office document previews
corepack enable
pnpm install --frozen-lockfile
pnpm check
pnpm devRun the API and media worker in separate terminals. Both processes must use the same database and storage configuration:
pnpm --filter @aeonic/api dev
pnpm --filter @aeonic/api dev:workerThe API listens on http://localhost:3001 by default. The dashboard listens on
http://localhost:4173 and proxies local API requests to port 3001.
curl http://localhost:3001/health/live
curl http://localhost:3001/health/ready
curl http://localhost:3001/api/v1/setupOpen http://localhost:3001/docs for the interactive API reference, or consume the machine-readable document at http://localhost:3001/openapi.json.
The simple-upload endpoint accepts exactly one raw media file per request. For example, after signing in and retaining the session cookie:
curl --request POST \
--cookie cookies.txt \
--header 'Content-Type: image/jpeg' \
--data-binary @photo.jpg \
'http://localhost:3001/api/v1/organizations/ORGANIZATION_ID/projects/PROJECT_ID/uploads?filename=photo.jpg'Service clients can send a project-scoped assets:write key in x-api-key. Supply
Content-Digest: sha-256=:BASE64_DIGEST: when end-to-end checksum verification is needed. Simple
uploads require Content-Length, default to private visibility, are limited to 100 MiB, and share a
configurable 10 GiB quota per project.
For unreliable networks and large files, use a tus 1.0 client with the project creation endpoint:
/api/v1/organizations/ORGANIZATION_ID/projects/PROJECT_ID/tus
Aeonic advertises creation, expiration, checksum, and termination. Clients must provide a
known Upload-Length and Base64-encoded filename and filetype metadata. The default resumable
limit is 5 GiB and unfinished uploads expire after 24 hours of inactivity. The staging directory
must be placed on persistent storage; completed bytes are moved into the configured local or
S3-compatible backend only after integrity and media-type validation.
Project usage, active reservations, remaining quota, backend health, and sanitized failure codes are available from:
/api/v1/organizations/ORGANIZATION_ID/projects/PROJECT_ID/storage
Ready public assets have immutable canonical URLs and may be fetched directly. Private assets can
be read with a cookie session or an assets:read project key, or shared temporarily by creating a
signed URL:
curl --request POST \
--cookie cookies.txt \
--header 'Content-Type: application/json' \
--data '{"expiresInSeconds":900,"disposition":"attachment"}' \
'http://localhost:3001/api/v1/organizations/ORGANIZATION_ID/projects/PROJECT_ID/assets/PUBLIC_ID/versions/1/delivery-url'The response URL is a bearer capability: keep its full query string private and do not modify it.
Signed URLs expire after 15 minutes by default. Documents are always served as attachments; images
and videos default to inline. Delivery supports GET, HEAD, validators, and one RFC byte range.
Use the interactive API reference for the authenticated and canonical URL shapes.
Ready video and document versions accept asynchronous derivative requests at:
/api/v1/organizations/ORGANIZATION_ID/projects/PROJECT_ID/assets/PUBLIC_ID/versions/1/derivatives
The response is immediately reusable as the status resource. Requests with the same source digest,
canonical operation, output format, and processor revision share one cache identity. Completed
content is available through the authenticated contentPath in the response; deleting the status
resource explicitly invalidates its cached output.
Use .env.example as the configuration reference. Environment variables can be
provided by your shell or process supervisor; automatic .env file loading is not currently part
of the runtime.
The optional AI profile is documented in Optional semantic search. Core services do not require it.
The optional stdio MCP server and its human approval boundary are documented in Approval-gated media workflows.
Public contract guarantees and supported environments are documented in API stability and deprecation and the support matrix. Release candidates follow the evidence-based release checklist.
For a no-CLI-after-installation experience, follow the Compose deployment guide. It covers secret generation, TLS, first-run setup, diagnostics, backup, and recovery. Review the upgrade and rollback guide before changing versions.
| Command | Purpose |
|---|---|
pnpm dev |
Build workspace dependencies and run development watchers |
pnpm --filter @aeonic/api dev:worker |
Run the media worker in watch mode |
pnpm --filter @aeonic/api start:worker |
Run the compiled media worker |
pnpm --filter @aeonic/api run doctor |
Run read-only deployment diagnostics after building |
pnpm build |
Produce clean ESM output for every package |
pnpm --filter @aeonic/api db:migrate |
Apply checked-in database migrations |
pnpm --filter @aeonic/api auth:schema |
Regenerate the Better Auth Drizzle schema |
pnpm --filter @aeonic/api db:generate |
Generate a reviewed migration after schema changes |
pnpm test |
Run the test suite |
pnpm --filter @aeonic/api test:s3 |
Run the opt-in live S3 compatibility contract |
pnpm bench:delivery |
Benchmark 1 MiB local original delivery at 100 requests per second |
pnpm bench:transform |
Benchmark the deterministic 12-megapixel image transform fixture |
pnpm bench:metadata |
Benchmark the authenticated metadata API with 100,000 assets |
pnpm security:audit |
Fail on high or critical production dependency advisories |
pnpm release:verify |
Check version, image, documentation, and workflow metadata consistency |
pnpm typecheck |
Run strict TypeScript checks |
pnpm lint |
Run static analysis |
pnpm format:check |
Verify formatting |
pnpm check |
Run the complete local/CI quality gate |
apps/
api/ Express control-plane API
dashboard/ React and Vite operator workspace
packages/
contracts/ Transport schemas and shared public types
scripts/ Repository maintenance scripts
Architecture research and internal planning are maintained separately from this source repository. User-facing documentation will expand only as corresponding behavior ships.
See CONTRIBUTING.md. Security issues should follow SECURITY.md.