Artiflow
OfficialUses Ceph as a private S3-compatible bucket for artifact revision and staging bytes.
Uses Cloudflare R2 as a private S3-compatible bucket for artifact revision and staging bytes.
Uses MinIO as a private S3-compatible bucket for artifact revision and staging bytes.
Persists Better Auth sessions, OAuth/JWT data, and artifact metadata; applies additive Drizzle migrations and supports a SELECT 1 health probe.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.lockis the single lockfile; there is nopackage-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; seeCONTRIBUTING.mdfor 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
bun install— install the pinned workspace dependencies frombun.lock, including the OpenCode plugin workspace: its dependencies resolve from the rootnode_modules, sotest,typecheckandbuildloadplugins/opencode/.bun run setup:pluginruns the same install with--frozen-lockfile, as CI does.bun run setup:local— create.env.localfrom.env.example(mode0600) and generateARTIFLOW_AUTH_SECRET. If the file already exists, it is preserved and the secret is added only when missing. An older.env.localwithout the secret can also be fixed withbun run setup:auth.Edit
.env.localand point it at your services:DATABASE_URL=postgres://USER:PASSWORD@HOST:5432/DBNAMEARTIFLOW_S3_ENDPOINT,ARTIFLOW_S3_BUCKET,ARTIFLOW_S3_ACCESS_KEY_ID,ARTIFLOW_S3_SECRET_ACCESS_KEYARTIFLOW_S3_REGIONandARTIFLOW_S3_FORCE_PATH_STYLEwhen needed.
bun run check:local— runsSELECT 1andHeadBucketagainst the configured services. It never creates anything.bun run db:migrate— apply the additive migrations to that database. Running it again is a no-op.bun run test— test suite (no services required).bun run typecheck— API and web TypeScript checks.bun run build— Vite production build plus API type check.bun run dev, then open http://127.0.0.1:5173/.Create a local account in the browser (development loopback only), then follow
docs/runbook.mdto 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://orpostgresql://.Add
?sslmode=require(orverify-full) when the server requires TLS.bun run db:migraterefuses a non-loopback host unlessARTIFLOW_ALLOW_REMOTE_MIGRATE=1is set explicitly. The productionmigratecontainer 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 usestaging/<sha256>.Use
ARTIFLOW_S3_FORCE_PATH_STYLE=1for R2 and most non-AWS providers.ARTIFLOW_S3_ENDPOINTmust be an absolutehttp(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).
Point a DNS
A/AAAArecord for your domain at the VPS; open ports 80 and 443.Install Docker and clone this repository on the VPS.
cp env.prod.example .env.prod, fill every value,chmod 600 .env.prod. Generate the auth secret withopenssl rand -hex 32.Make sure the external database and bucket exist, then fill the connection entries in
.env.prod.bun run deploy:up— builds both images, applies migrations to the external database (guarded by the explicitARTIFLOW_ALLOW_REMOTE_MIGRATE=1opt-in) and starts the stack. Caddy obtains and renews the TLS certificate.bun run deploy:logsto watch,bun run deploy:downto stop. Upgrades aregit pull && bun run deploy:up(migrations re-run as a no-op when applied).
Local ports
Port | Service | Notes |
5173 | UI (Vite) |
|
8787 | API (Bun/Hono) |
|
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-sessionafter 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:localvalidates the configured PostgreSQL and S3 bucket (SELECT 1+HeadBucket).The API answers
GET /api/healthwith 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 frombun 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 theui://artiflow/artifact-viewerresource; text-only clients keep the plain JSON result.Known limits are documented honestly in
docs/runbook.md(legacy non-UUID artifacts, no/sharerate 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 plusPOST /api/auth/registration/completeand an ordinary sign-in (scripts/fixture-accounts.mjs), never through public sign-up. It therefore needs the API environment the operator command validates (DATABASE_URLand theARTIFLOW_S3_*names), the same public origin, andbunonPATHorARTIFLOW_BUN; because theuser:invitealias runsbunitself, the helper also puts the selected executable's directory on the childPATH.
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:
Quickstart — connect an agent, publish a first page, share it.
Install Artiflow and Operate and upgrade — self-hosting, verification, upgrades, backups and restore.
Development setup — toolchain, code layout, tests and how to add a page.
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:
/sharehas no rate limiting. Thedocker-compose.prod.ymlpath 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Artifact store for AI agents. Hosted OAuth at mcp.artifacta.io/mcp; local stdio via npm/PyPI.
Publish and share access-controlled Markdown documents from any MCP-enabled AI tool.
AgentDocs (agentdocs.eu) MCP: read, search, write, comment, share & attach images to Markdown docs.
Publish your agent's Markdown as shareable web pages with revision provenance and comments.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server that turns agent-generated Markdown, HTML, and text into persistent links, with tools to create, update, remove, list, and retrieve artifacts.MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.2MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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.1MIT
- AlicenseAqualityBmaintenanceOne 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-site2628Apache 2.0