Skip to main content
Glama
Artiflow
by guidobuilds

Artiflow

Artiflow is a private library for self-contained HTML artifacts and Markdown documents created over MCP: agents write content through authenticated MCP tools, and owners manage access (sharing, public links, deletion) from a browser dashboard.

This repository runs the application only. PostgreSQL and S3-compatible object storage are external services that you provide and operate; the application never starts, creates, provisions or owns them. The one exception is the disposable loopback test stack in docker-compose.yml (PostgreSQL + Garage), which serves the integration suites and never touches real data.

Requirements

  • Bun >=1.2 (verified on 1.3.10) — the only package manager and the API runtime, in development (bun run dev) and in production (the API image). bun.lock is the single lockfile; there is no package-lock.json.

  • Node.js >=24.0.0 (verified on v24.17.0) — the runtime for the Vite dev server, the repository scripts and the test runner (node --test; see CONTRIBUTING.md for why the suite stays on Node).

  • A reachable PostgreSQL 16 database and role.

  • A private S3-compatible bucket and credentials (AWS S3, Cloudflare R2, MinIO, Ceph, or any compatible provider).

  • Docker for the integration-test stack or the production images.

Related MCP server: open-artifacts

Quick path

  1. bun install — install the pinned workspace dependencies from bun.lock, including the OpenCode plugin workspace: its dependencies resolve from the root node_modules, so test, typecheck and build load plugins/opencode/. bun run setup:plugin runs the same install with --frozen-lockfile, as CI does.

  2. bun run setup:local — create .env.local from .env.example (mode 0600) and generate ARTIFLOW_AUTH_SECRET. If the file already exists, it is preserved and the secret is added only when missing. An older .env.local without the secret can also be fixed with bun run setup:auth.

  3. Edit .env.local and point it at your services:

    • DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/DBNAME

    • ARTIFLOW_S3_ENDPOINT, ARTIFLOW_S3_BUCKET, ARTIFLOW_S3_ACCESS_KEY_ID, ARTIFLOW_S3_SECRET_ACCESS_KEY

    • ARTIFLOW_S3_REGION and ARTIFLOW_S3_FORCE_PATH_STYLE when needed.

  4. bun run check:local — runs SELECT 1 and HeadBucket against the configured services. It never creates anything.

  5. bun run db:migrate — apply the additive migrations to that database. Running it again is a no-op.

  6. bun run test — test suite (no services required).

  7. bun run typecheck — API and web TypeScript checks.

  8. bun run build — Vite production build plus API type check.

  9. bun run dev, then open http://127.0.0.1:5173/.

  10. Create a local account in the browser (development loopback only), then follow docs/runbook.md to create artifacts over MCP and manage them.

Use that exact IPv4 address. localhost can resolve to an unrelated IPv6 listener on some machines and show a different application.

bun run test:auth and bun run test:oauth run real HTTP integration suites against an isolated PostgreSQL database. Point DATABASE_URL at a disposable database you control before running them.

External services

PostgreSQL

  • Any PostgreSQL 16 server reachable from the API process.

  • The URL must use postgres:// or postgresql://.

  • Add ?sslmode=require (or verify-full) when the server requires TLS.

  • bun run db:migrate refuses a non-loopback host unless ARTIFLOW_ALLOW_REMOTE_MIGRATE=1 is set explicitly. The production migrate container sets it because the managed database is the intended target.

  • The app never creates roles or databases.

S3-compatible object storage

  • The bucket must already exist and stay private.

  • The app never creates buckets, ACLs or bucket policies.

  • Revision bytes use one key per revision (artifacts/<revision id>); staging bytes use staging/<sha256>.

  • Use ARTIFLOW_S3_FORCE_PATH_STYLE=1 for R2 and most non-AWS providers.

  • ARTIFLOW_S3_ENDPOINT must be an absolute http(s) URL. Use HTTPS in production.

Production deployment (VPS)

For the full self-hosted topology (dedicated subdomain, proxy Host requirements, harness connection, cloud-agent prerequisites and a pre-flight checklist) read docs/deployment-guide.md.

The production stack is three containers: migrate (one-shot), api, and web (Caddy serving the built frontend, reverse-proxying the API and terminating TLS). PostgreSQL is an external managed database and object storage is an external S3-compatible bucket (for example Cloudflare R2).

  1. Point a DNS A/AAAA record for your domain at the VPS; open ports 80 and 443.

  2. Install Docker and clone this repository on the VPS.

  3. cp env.prod.example .env.prod, fill every value, chmod 600 .env.prod. Generate the auth secret with openssl rand -hex 32.

  4. Make sure the external database and bucket exist, then fill the connection entries in .env.prod.

  5. bun run deploy:up — builds both images, applies migrations to the external database (guarded by the explicit ARTIFLOW_ALLOW_REMOTE_MIGRATE=1 opt-in) and starts the stack. Caddy obtains and renews the TLS certificate.

  6. bun run deploy:logs to watch, bun run deploy:down to stop. Upgrades are git pull && bun run deploy:up (migrations re-run as a no-op when applied).

Local ports

Port

Service

Notes

5173

UI (Vite)

http://127.0.0.1:5173/, same-origin /api proxy

8787

API (Bun/Hono)

GET /api/health reports the database and storage probes

PostgreSQL and object storage listen wherever your provider exposes them; this repository does not publish or manage those ports.

Approved stack: React/Vite/TypeScript, Bun/Hono, official MCP SDK, PostgreSQL with Drizzle, private S3-compatible object storage and Better Auth. Google/GitHub sign-in are optional per deployment; the local email/password form is development-only.

Auth and database foundation

The migration creates the Better Auth user, session, account and verification tables plus the OAuth/JWT and artifact tables, and is tracked in drizzle.__drizzle_migrations.

The API mounts the real Better Auth handler at /api/auth/* and serves a public, uncached GET /api/auth/capabilities with exactly one boolean. The browser form appears only when the server's own development guard enables email/password, so a production build served by a development API still behaves correctly. Auth does not depend on S3, so health can stay degraded while sessions still work.

Sign in with a local account

  • Signed out, the panel offers Create account (name, email, password) or Sign in.

  • Signed in, it shows the real name and email from the session and a Sign out button.

  • Passwords are throwaway values of at least 8 characters. No email is sent and no provider (Google, GitHub) is connected unless you configure one, so there are no social buttons by default.

  • Nothing is written to browser storage: the HttpOnly cookie is carried by the browser and identity is re-read from GET /api/auth/get-session after every mutation.

Email/password is enabled in production, or in development when NODE_ENV=development, ARTIFLOW_DEMO_AUTH=1 and a loopback ARTIFLOW_PUBLIC_ORIGIN all agree. Base URL and trusted origin are fixed to that public origin, so the browser uses the Vite /api proxy. Mutations require the exact Origin and JSON; session reads may omit Origin. CSRF/origin checks, HttpOnly, SameSite=Lax and Path=/ stay on, cookie-cached sessions and telemetry stay off.

Current checkpoint

  • bun run check:local validates the configured PostgreSQL and S3 bucket (SELECT 1 + HeadBucket).

  • The API answers GET /api/health with HTTP 200 when both probes pass and 503 when either external service is unavailable.

  • /api/auth/* is mounted and the browser sign-in/sign-out flow works for development loopback. Public sign-up is closed: a new account comes only from bun run user:invite EMAIL, which prints a single-use /register#token=… link that opens a form with the email address fixed. Artifacts persist in the configured PostgreSQL + bucket; MCP tools are live at /mcp (bearer-only, OAuth 2.1 with PKCE and browser consent); the dashboard lists, views (sandboxed), shares, publishes links, edits markdown and deletes artifacts. Hosts that implement MCP Apps (SEP-1865) render committed artifacts inline through the ui://artiflow/artifact-viewer resource; text-only clients keep the plain JSON result.

  • Known limits are documented honestly in docs/runbook.md (legacy non-UUID artifacts, no /share rate limiting, development-only cookies). Staged-chunk garbage is collected automatically every 15 minutes.

  • The remaining local driver (scripts/e2e-full-cycle.mjs) is a manual probe against a running local stack, not a self-contained suite. It creates its throwaway accounts through that same command plus POST /api/auth/registration/complete and an ordinary sign-in (scripts/fixture-accounts.mjs), never through public sign-up. It therefore needs the API environment the operator command validates (DATABASE_URL and the ARTIFLOW_S3_* names), the same public origin, and bun on PATH or ARTIFLOW_BUN; because the user:invite alias runs bun itself, the helper also puts the selected executable's directory on the child PATH.

Secrets

setup:local creates .env.local with mode 0600, and the file is git-ignored. It never prints values. Never commit, paste or replace generated values with personal credentials. Service credentials belong in the external provider, not in this repository.

Documentation

The documentation site lives in apps/web and targets https://artiflow.dev/docs:

Repository-facing notes stay in docs/ (start with docs/architecture/README.md and docs/runbook.md); CONTRIBUTING.md remains the contribution entry point.

Contributing

Read CONTRIBUTING.md before opening a pull request: it covers local setup, branch and commit conventions, the checks to run (tests, typecheck, build), migrations and secrets.

License

Artiflow is released under the MIT License.

Agent skills

skills/ holds the canonical agent skills (creating-artifacts, using-artiflow) that every harness integration installs or packages — see skills/README.md for the per-harness install matrix.

Not implemented

  • Dashboard upload routes: content is created through MCP only, by design.

  • Production hardening: /share has no rate limiting. The docker-compose.prod.yml path exists but a fresh-machine production run has not been verified end to end.

  • Local service provisioning for the application: PostgreSQL and object storage are external by design. The Compose stack is test-only.

Next step

Read docs/runbook.md: it covers first run, the MCP tool flow (PKCE + consent + bearer tokens), dashboard management (share by email, public links, double-confirm deletion) and troubleshooting. The architecture docs start at docs/architecture/README.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to publish, retrieve, update, and delete hosted HTML, Markdown, Mermaid, and SVG artifacts and to create, list, or revoke shareable links through authenticated, scope-enforced tools. It exposes artifact hosting over Streamable HTTP so any MCP client can manage content on a self-hosted instance using a Bearer agent API key.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable agents to author, query, and maintain a self-hosted wiki through typed tools backed by SQLite, including full-text search, revisions, links, tags, media, and correction work queues. It supports configurable read, author, and admin tool surfaces for creating, updating, deleting, reviving, and section-editing pages.
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      One place for every AI agent's pages and docs. Publish HTML, build folders, ZIPs, PDFs and Office documents as sandboxed, versioned share links, then search, read and update them later from any MCP client. Sign in with Google or GitHub via OAuth. Open source and self-hostable: https://github.com/lexmount/artifact-site
      26
      28
      Apache 2.0