Prismloom

Prismloom is an open-source, Agent-native pixel asset production platform. One versioned Job contract, compiler, runtime, and policy set drive the Web UI, Bun CLI, and Agent Skill. The only optional proprietary component is hosted image-generation compute.

What ships

• Guided Web production, review, gallery, character, pack, share, account, credit, and API-key flows.
• A machine-first Bun CLI with stable JSON envelopes and deterministic exit codes.
• An Agent Skill that invokes the CLI without duplicating business logic or carrying secrets.
• Local asset processing, PNG inspection, semantic pixel-bloom derivation, deterministic export, and local Studio foundations.
• BYO OpenAI-compatible generation for user-owned local or private endpoints.
• A single-instance hosted service with SQLite, local blob storage, fixed quotes, credit reservation/finalization/refund, and asynchronous jobs.
• Official hosted adapters for OpenAI gpt-image-2, Google gemini-3.1-flash-image, and Google gemini-3-pro-image.

Video generation, public registration, payment processing, and consumer-subscription OAuth pooling are not part of v1.

Requirements and installation

Prismloom requires Bun 1.3.14 or newer.

From source:

bun install --frozen-lockfile
bun run build
bun run cli -- --version

To exercise the distributable package locally:

bun pm pack
bun add --global ./prismloom-0.1.0.tgz
prismloom --version

The package contains the launcher, compiled CLI, migrations, Agent Skill, Apache license, notice, and retained third-party license text.

Workspace and CLI contract

A workspace is a real directory containing prismloom.json. Prismloom searches the current directory and its ancestors, or accepts an exact --workspace <directory>. It never creates a workspace implicitly.

Minimal local workspace:

{
  "defaultMode": "local"
}

defaultMode is exactly local, byo, or hosted. --mode overrides it for one invocation. --json returns the stable CLI envelope; without it, successful non-version commands print the data object as formatted JSON. Runtime state stays under .prismloom/ inside the canonical workspace.

Core commands:

prismloom [--workspace DIR] [--mode local|byo|hosted] [--json] --version
prismloom job check JOB.json
prismloom job compile [JOB.json]
prismloom job compile --intent INTENT.json
prismloom job run COMPILED-JOB.json [--accept-quote REF] [--idempotency-key KEY]
prismloom job poll JOB-ID [--wait DURATION] [--interval DURATION]
prismloom inspect JOB-OR-CANDIDATE-ID
prismloom review approve CANDIDATE-ID
prismloom review reject CANDIDATE-ID
prismloom bloom derive --source APPROVED-ASSET-ID --palette PALETTE.json
prismloom export APPROVED-ASSET-OR-PACK-ID
prismloom model list
prismloom model show PROFILE-ID
prismloom doctor

Use job check before compilation. job compile returns the shared canonical manifest, digest, and execution plan used by Web and hosted APIs. Hosted job run first returns an authoritative fixed quote; submit the same compiled Job with --accept-quote and an idempotency key. Polling is the supported asynchronous status mechanism.

All supplied workspace paths are canonicalized and must remain inside the workspace. Symlink escapes and non-regular inputs are rejected.

Execution modes

Local

Local mode performs deterministic, network-free asset work. It supports asset-process Jobs, inspection, review, pixel-bloom derivation, and export. It deliberately refuses image-generation Jobs because no provider exists in this mode.

The local runtime persists SQLite state, blobs, exports, and pending submissions below .prismloom/. A repeated export of unchanged approved inputs produces the same digest. Run prismloom doctor --mode local --json before a production batch.

BYO

BYO mode calls an OpenAI-compatible endpoint owned and controlled by the user. It is intended for loopback, LAN, or explicitly allowed remote HTTPS endpoints, including a self-hosted Sub2API deployment. It is never a route for hosted Prismloom to import or pool consumer OAuth credentials.

Set all three deployment-owned JSON arrays:

• PRISMLOOM_BYO_CONFIGURATIONS: strict endpoint records (id, endpoint, model, credential reference, network policy, and optional transport bounds).
• PRISMLOOM_BYO_MAPPINGS: local-user/profile/configuration bindings.
• PRISMLOOM_BYO_PROFILES: versioned ModelProfile records whose provider is openai-compatible.

The exact contracts are ByoEndpointConfiguration and ByoUserProfileMapping in src/app/byo/config.ts, plus ModelProfileSchema in src/contracts/provider.ts. Each environment value must be a JSON array. Non-secret mappings and profiles may instead live under byo.mappings and byo.profiles in prismloom.json; endpoint and credential data must not.

Credentials are references, not Job fields:

{
  "credential": {
    "environmentVariable": "MY_IMAGE_API_KEY"
  }
}

An absolute secretFile is also accepted when it is a regular owner-only file. Environment values take precedence. Never put endpoints, credentials, cookies, headers, or OAuth material in Jobs, prompts, workspace manifests, logs, or Agent Skill files. Validate the resolved setup with prismloom doctor --mode byo --json and prismloom model list --mode byo --json.

Hosted

Hosted CLI mode talks only to the fixed Prismloom HTTPS origin and requires PRISMLOOM_TOKEN. Use a fixed-scope API key created in the account UI/API; available scopes are jobs:read, jobs:write, assets:read, assets:write, and profile:read.

export PRISMLOOM_TOKEN='prismloom_api_key_value'
prismloom model list --mode hosted --json
prismloom job compile job.json --mode hosted --json

Hosted generation uses only official provider APIs. Provider credentials remain deployment secrets and are never accepted from a browser, Job, CLI argument, share link, or consumer-subscription account.

Model profiles and quotes

Profiles are immutable, versioned policy records. The built-in v1 catalog contains:

Profile	Version	Provider model
openai-gpt-image-2	2026-07-15	gpt-image-2
gemini-nano-banana-2	2026-07-15	gemini-3.1-flash-image
gemini-nano-banana-pro	2026-07-15	gemini-3-pro-image

Use prismloom model list and prismloom model show instead of hard-coding capabilities or prices. A quote binds the canonical Job digest, profile version, candidate count, provider canvas, transformations, and point amount. Submission reserves that amount; success finalizes actual accepted work, while system failures refund the reservation. User rejection or cancellation does not masquerade as a system refund.

Self-hosted operator runbook

The supplied Docker Compose deployment is a single-instance topology: one service, one worker, one SQLite writer, one local data volume, and default concurrency of two provider requests/jobs. Do not scale replicas above one or place the SQLite file on an eventually consistent/network filesystem.

Create four owner-readable secret files with no trailing commentary:

• a random session secret of at least 32 characters;
• a random credential-encryption key of at least 32 characters;
• an official OpenAI API key;
• an official Google Gemini API key.

Set their absolute host paths and the exact public HTTPS origin:

export PRISMLOOM_TRUSTED_ORIGINS='https://prismloom.example.com'
export PRISMLOOM_SESSION_SECRET_PATH='/secure/prismloom/session-secret'
export PRISMLOOM_CREDENTIAL_ENCRYPTION_KEY_PATH='/secure/prismloom/credential-key'
export PRISMLOOM_OPENAI_API_KEY_PATH='/secure/prismloom/openai-key'
export PRISMLOOM_GEMINI_API_KEY_PATH='/secure/prismloom/gemini-key'
docker compose up --build -d
curl --fail http://127.0.0.1:3000/readyz

Compose publishes on 127.0.0.1:3000 by default. Terminate TLS in a trusted reverse proxy, preserve the original HTTPS origin, limit request size there as well, and expose no direct provider or SQLite port.

Bootstrap accounts and credits

There is no public signup, password-reset email, or payment gateway. Bootstrap exactly one administrator before public exposure:

docker compose run --rm --entrypoint bun prismloom \
  src/cli/entry.ts admin account bootstrap admin@example.com --json

The command prints a one-time bootstrap password. Store it only long enough to sign in and complete the mandatory password change.

All later administrator commands require PRISMLOOM_TOKEN to contain a live administrator session bearer obtained through the HTTPS login flow. Pass it to the one-off container without writing it into Compose or shell history, and unset it immediately afterward:

export PRISMLOOM_TOKEN='active_administrator_session_bearer'
docker compose run --rm --entrypoint bun -e PRISMLOOM_TOKEN prismloom \
  src/cli/entry.ts admin account create artist@example.com --role member --json
docker compose run --rm --entrypoint bun -e PRISMLOOM_TOKEN prismloom \
  src/cli/entry.ts admin credit top-up ACCOUNT-ID 100 --reason 'manual top-up' --json
unset PRISMLOOM_TOKEN

Account creation and password reset return one-time bootstrap passwords. Credit top-ups and revocations require positive integer points and a durable operator reason; every mutation is ledgered. Disable accounts instead of deleting audit history.

Retention

Ordinary uploads and unapproved candidates are retained for seven days by default. Approved assets, packs, and characters are durable production records and are not removed by ordinary-candidate cleanup. Signed share links are finite-lived credentials; revoke or allow them to expire rather than treating them as public asset URLs.

The cleanup worker runs daily by default. Keep PRISMLOOM_NORMAL_RETENTION_DAYS=7 unless a deliberate policy change is reflected in customer expectations and storage planning.

Backup and restore

The prismloom-data volume is one recovery unit: it contains prismloom.sqlite plus durable blobs. A database-only copy is not a complete asset backup.

1. Gracefully stop the service so the SQLite writer guard is released.
2. Snapshot or archive the entire prismloom-data volume to encrypted storage.
3. Verify the copied SQLite database with PRAGMA integrity_check and PRAGMA foreign_key_check, and verify that blob files were included.
4. Restart the service and retain the backup according to operator policy.

To restore, stop the service, restore the entire volume into an empty target, remove no individual WAL/SHM file by hand, start the same Prismloom release, and wait for /readyz. deploy/backup.ts exposes verified SQLite snapshot/restore helpers for integrations; restore refuses to proceed without an explicit stopped-service acknowledgement. Test recovery periodically on an isolated host.

Agent Skill

The packaged Skill is skills/prismloom. Validate and install it with the CLI:

prismloom skill validate skills/prismloom --json
prismloom skill install skills/prismloom --target /absolute/agent-skills-directory --json

The installer rejects symlink/path escapes and incompatible CLI versions. The Skill contains prompts and metadata only: it invokes prismloom, consumes the same JSON envelopes, and contains no provider client, business rule, executable script, or secret. Configure PRISMLOOM_TOKEN or BYO credentials in the CLI process environment, never inside the Skill package.

Security boundary

• Browsers call Prismloom only; they never call OpenAI, Gemini, or BYO endpoints directly.
• Hosted Prismloom accepts official provider credentials only from owner-readable secret files.
• Consumer OAuth cookies, refresh tokens, ChatGPT/Gemini subscription credentials, and credential pooling are prohibited.
• Session cookies are HTTPS/HttpOnly; state-changing browser routes require exact-origin and CSRF checks.
• API keys are opaque, fixed-scope bearer values shown once. Query-string credentials are rejected.
• Jobs select published profile IDs and versions, never endpoints, models, headers, or credentials.
• Provider errors, CLI envelopes, logs, and persisted diagnostics are bounded and redacted.
• Uploads, workspace paths, archives, PNGs, provider responses, and redirects are validated before trust.

If a secret may have reached output or storage, rotate it; do not rely on redaction as revocation.

Development and release verification

bun install --frozen-lockfile
bun run check
openspec validate prismloom-v1 --strict --no-interactive

bun run build type-checks and builds both Web and CLI artifacts. bun test covers contracts, shared compiler/runtime behavior, providers, security boundaries, HTTP/API flows, Web controllers/components, CLI/Skill equivalence, deployment, and end-to-end release scenarios.

License and attribution

Prismloom is licensed under Apache-2.0; see LICENSE.

Modified portions of imgasset v1.5.0 are retained under the upstream MIT license. The required attribution is in NOTICE, and the complete upstream license text is in LICENSES/imgasset-MIT.txt. Prismloom and its package distributions retain both files.