ArtifactSmith

ArtifactSmith

ArtifactSmith is an open source artifact server for AI agents.

Examples

Built on the hosted copy from public sources (Ready.gov and the U.S. Bureau of Labor Statistics). The meeting notes are fictional. No sign-up needed to open them.

• Web page: Hurricane readiness checklist, from Ready.gov guidance.
• Chart report: U.S. jobs report in charts, unemployment and payrolls, January 2024 to September 2026, from BLS data.
• PDF: U.S. labor market brief, one page, September 2026, from BLS data.
• Word document: Kickoff meeting notes, for a fictional library website project. Downloads a .docx.
• Excel workbook: Unemployment and payrolls, 2024 to 2026, monthly figures with a sources sheet. Downloads a .xlsx.

Agents call it to turn their work into documents: web pages, PDFs, Word files, spreadsheets and Markdown. Each artifact is versioned and stays private until someone shares it, and a shared link can be revoked at any time.

It's for people who run their own agents and want artifacts like the ones in Muse on their own servers.

Try it before you install: https://artifactsmith.neuralami.ai/try. I run a copy you can point your MCP client at. Claude.ai, Claude Desktop, Claude Code and Cursor sign in with OAuth using your email; a pasted token also works. It is capped at 20 builds and runs on my server.

What it does

ArtifactSmith gives agents tools to create, edit, export (PDF, Word, Excel, Markdown), share, and revoke documents. It works with any OpenAI-compatible model endpoint. The idea comes from Meta's Muse artifacts.

Requirements: Docker Engine with the Compose plugin. A model key (OpenAI-compatible API or local endpoint) is needed to build pages; publishing ready-made Markdown or HTML works without one.

Quickstart

Cline follows llms-install.md.

cp .env.example .env

Set OPENAI_API_KEY (or AM_LLM_KEY). Change AM_LLM_BASE / AM_DEFAULT_MODEL

only if you are not using the default OpenAI host and model.

Object-store keys: leave them empty and run ./scripts/ensure-local-env.sh,

or paste your own AM_STORE_KEY and AM_STORE_SECRET.

./scripts/ensure-local-env.sh docker compose up -d --build

Create a token (prints the raw value once; only its hash is stored).

--workspace is a label that scopes every artifact the token can see

(e.g. alpha, team-a). Tokens cannot cross workspaces.

docker compose exec server artifactsmith token add --name agent --workspace alpha

publish stores a page you already wrote and does not call the model, so the next step works when the key is empty. Paste the token printed above, then run this. It prints a share URL.

export AM_TOKEN='paste-the-token'

docker compose exec -T -e AM_TOKEN server python - <<'PY' import asyncio import json import os from datetime import timedelta

from mcp import ClientSession from mcp.client.streamable_http import streamablehttp_client

URL = "http://127.0.0.1:8780/mcp" PAGE = """# Pilot store brief

The pilot store code is HARBOR-17. It is the identifier used on inventory, support, and rollout reports. """

def parse(result): if result.structuredContent is not None: return result.structuredContent return json.loads(result.content[0].text)

async def main(): headers = {"Authorization": "Bearer " + os.environ["AM_TOKEN"]} async with streamablehttp_client(URL, headers=headers) as (read, write, _session): async with ClientSession(read, write) as session: await session.initialize() created = parse( await session.call_tool( "publish", {"display_name": "Pilot store brief", "markdown": PAGE}, read_timeout_seconds=timedelta(seconds=120), ) ) done = parse( await session.call_tool( "status", {"job_id": created["job_id"], "wait": 90}, read_timeout_seconds=timedelta(seconds=120), ) ) if done.get("status") != "done": raise SystemExit(json.dumps(done)) shared = parse( await session.call_tool( "share", {"artifact_id": created["artifact_id"]}, read_timeout_seconds=timedelta(seconds=120), ) ) print(shared["url"])

asyncio.run(main()) PY

The server reads AM_LLM_BASE, AM_LLM_KEY or OPENAI_API_KEY, and AM_DEFAULT_MODEL from .env. The default base is https://api.openai.com. A trailing /v1 on the base is fine; the client appends /v1/chat/completions itself. create needs a key or a local OpenAI-compatible endpoint. With an empty key, a failed create reports that OPENAI_API_KEY / AM_LLM_KEY is empty. Run docker compose up -d again so the change takes effect.

Host ports bind to 127.0.0.1:

• http://127.0.0.1:8780/mcp is the MCP API (bearer token required)
• http://127.0.0.1:8780/app/ is My pages (paste the same token; the browser gets a session cookie)
• http://127.0.0.1:8781/ is the cookieless preview and share origin (/p/…, /s/…)

Use the published image

ghcr.io/vrijsinghani/artifactsmith:0.1.0 is published for linux/amd64 on each release. Building from source (the Compose steps above) stays the default.

Connect a client

Claude.ai: Customize → Connectors → + Add → Add custom connector. Paste https://artifactsmith.neuralami.ai/mcp, select Connect, and sign in with your email. The connector then works in the Claude desktop and phone apps too. Free plans allow one custom connector. On Team and Enterprise plans an owner adds it first.

github.com/vrijsinghani/Artifactsmith is the copy you run yourself. On the hosted copy, Claude Desktop, Claude Code, and Cursor sign in with OAuth at https://artifactsmith.neuralami.ai/mcp. On your own copy they use a token. The MCP endpoint on this machine is http://127.0.0.1:8780/mcp. Send the token from artifactsmith token add as Authorization: Bearer YOUR_TOKEN. The header value starts with Bearer .

ChatGPT Free, Go, and Plus cannot add a custom MCP server. Pro can add one with read and fetch access only, so it cannot build pages. A ChatGPT Business, Enterprise, or Edu admin can add it on the web; it signs in with OAuth.

ChatGPT users can use it from OpenAI's Codex CLI instead: run codex mcp add artifactsmith --url https://artifactsmith.neuralami.ai/mcp, then codex mcp login artifactsmith, and sign in with your email.

Claude Desktop stores the config in claude_desktop_config.json (Settings → Developer → Edit Config). The snippet runs npx and mcp-remote, which needs Node.js. Restart Claude Desktop after saving.

{

"mcpServers": { "artifactsmith": { "command": "npx", "args": ["-y", "mcp-remote", "http://127.0.0.1:8780/mcp", "--header", "Authorization:${AUTH_HEADER}"], "env": { "AUTH_HEADER": "Bearer YOUR_TOKEN" } } } }

Claude Code stores .mcp.json, or run:

claude mcp add --transport http artifactsmith http://127.0.0.1:8780/mcp --header "Authorization: Bearer YOUR_TOKEN"

{

"mcpServers": { "artifactsmith": { "type": "http", "url": "http://127.0.0.1:8780/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

Cursor stores ~/.cursor/mcp.json, or .cursor/mcp.json in the project.

{

"mcpServers": { "artifactsmith": { "url": "http://127.0.0.1:8780/mcp", "headers": { "Authorization": "Bearer YOUR_TOKEN" } } } }

Example prompt: Create a one-page brief named Pilot store brief. Pass this as source_content: The pilot store code is HARBOR-17. It is the identifier used on inventory, support, and rollout reports.

artifactsmith stdio can list tools on stdin and stdout and does not listen. It cannot use the object store or the model, so it cannot build or publish a page.

Serving on your network or behind a proxy

Compose publishes API (8780) and preview/share (8781) on AM_BIND_ADDRESS (default 127.0.0.1). Cards and links use AM_API_URL, AM_PREVIEW_URL, and AM_SHARE_URL (empty AM_SHARE_URL falls back to AM_PREVIEW_URL). Exposing the ports without TLS puts bearer tokens and artifact content on the wire in cleartext.

LAN access

Bind on all interfaces (or a specific NIC IP) and point the public URL variables at the address clients will open:

# .env  (192.0.2.10 is documentation-range; substitute your LAN IP)

AM_BIND_ADDRESS=0.0.0.0 AM_API_URL=http://192.0.2.10:8780 AM_PREVIEW_URL=http://192.0.2.10:8781 AM_SHARE_URL=http://192.0.2.10:8781 AM_ALLOWED_HOSTS=192.0.2.10:8780,127.0.0.1:8780,localhost:8780

Then docker compose up -d --build. Clients open http://192.0.2.10:8780/mcp and preview/share links use 192.0.2.10, not 127.0.0.1. Browser-based MCP clients also need AM_ALLOWED_ORIGINS set to the page origin.

Share and preview URLs are built from AM_SHARE_URL / AM_PREVIEW_URL when the server returns them. Links you copied before switching to LAN serving still use the old base host; call share again (or copy the URL from inspect / status) after changing those settings.

Reverse proxy with TLS

Keep the host bind on loopback and terminate TLS on nginx or Caddy. Set the public URLs and allow-lists to the external hostname:

# .env

AM_BIND_ADDRESS=127.0.0.1 AM_API_URL=https://artifacts.example.com AM_PREVIEW_URL=https://preview.artifacts.example.com AM_SHARE_URL=https://preview.artifacts.example.com AM_ALLOWED_HOSTS=artifacts.example.com AM_ALLOWED_ORIGINS=https://artifacts.example.com

Minimal Caddy example (API on 443, preview on a second hostname):

artifacts.example.com {

reverse_proxy 127.0.0.1:8780 } preview.artifacts.example.com { reverse_proxy 127.0.0.1:8781 }

Minimal nginx snippet for the API host:

server {

listen 443 ssl; server_name artifacts.example.com;

ssl_certificate / ssl_certificate_key omitted

location / { proxy_pass http://127.0.0.1:8780; proxy_set_header Host $host; proxy_set_header Authorization $http_authorization;

status wait can be up to 90s; nginx defaults cut at 60s.

proxy_read_timeout 120s; proxy_send_timeout 120s; } }

When AM_ALLOWED_HOSTS lists only the public hostname, a local curl http://127.0.0.1:8780/mcp gets HTTP 421 (DNS-rebinding protection). Point clients at the proxied hostname instead. Browser-based MCP clients send an Origin header; set AM_ALLOWED_ORIGINS to that origin or the request is rejected.

MCP client on another machine

Point the client at {AM_API_URL}/mcp and send the token as Authorization: Bearer (the value printed once by artifactsmith token add). The header value starts with Bearer . artifactsmith stdio can list tools on stdin and stdout and does not listen. It cannot use the object store or the model, so it cannot build or publish a page. Example:

URL:    http://192.0.2.10:8780/mcp

Header: Authorization: Bearer asmb_…

How it works

Agents talk to ArtifactSmith over MCP. They pass the user's request as verbatim_request and any research as source_content or source_files. create starts a private build and does not publish a share link. Want a styled page? Pass Markdown to publish and it is styled automati