Documentation

Artifact Use

Your coding agent publishes HTML tools, dashboards, PDFs, and whole static folders to one stable URL — with access gates, versioning, and comments built in. This page is the product manual for both the humans and the agents involved.

In a hurry? Sign in at artifacts.iofold.com/admin, copy the ready-made connect prompt, and paste it to any agent. That one paste is the entire setup.

Overview

Artifact Use turns agent output into links people can open and review:

Agents publish over MCP, CLI, or plain HTTP — single HTML files or complete folders with images, data, and PDFs. Versions are immutable and promoted atomically.
People review at one stable link behind an email, verified-email, or allowlist gate, and comment directly on the artifact.
Work loops back — views and feedback are readable through the same API, so the next agent iteration starts where the review ended.

Everything is machine-readable. Agents can start at /llms.txt (summary) or /llms-full.txt (full agent guide).

Quickstart

Sign in at artifacts.iofold.com/login — email code, password, or Google. Your first sign-in creates a workspace.
Copy the connect prompt. When your workspace hasn't published recently, the admin shows a ready one-paste prompt under Agent setup. It carries a scoped publish token, endpoints, and instructions.
Paste it to your agent — Claude Code, Codex, or anything that can call HTTP. The agent verifies itself and knows how to publish.
Ask for an artifact. "Publish this prototype with an email gate." The agent replies with a stable link under /go/….
Share the link. Views and comments land back in your admin and in your agent's API.

Connect an agent

Two paths — pick by what your agent supports. Both end with the same capability: publish and manage artifacts in your workspace.

Path A · OAuth

Claude Code & MCP-proper clients

The smoothest path when the agent supports MCP OAuth: no tokens to copy, the agent signs in as you in the browser.

claude mcp add --transport http \
  artifact-use https://artifacts.iofold.com/mcp
# then /mcp in Claude Code → Authenticate

Other OAuth-capable MCP clients need only the config:

{
  "mcpServers": {
    "artifact-use": { "type": "http",
      "url": "https://artifacts.iofold.com/mcp" }
  }
}

Path B · Bearer token

Codex & agents with weak OAuth

One paste is the whole setup: in Admin → Agent setup, copy the ready prompt (30-day scoped token embedded) into the agent chat. Revoke it anytime from the same page.

Codex specifically — export the token and point the MCP server at it:

# shell
export ARTIFACT_USE_API_BASE=https://artifacts.iofold.com
export ARTIFACT_USE_TOKEN='au_creator_…'

# ~/.codex/config.toml
[mcp_servers.artifact-use]
url = "https://artifacts.iofold.com/mcp"
bearer_token_env_var = "ARTIFACT_USE_TOKEN"

Which path? Claude Code → Path A. Codex → Path B (its MCP OAuth token refresh is unreliable). Anything else that can send an HTTP header → Path B works everywhere. Either way, the agent verifies itself with GET /api/v1/me and should read /llms-full.txt once for publishing rules and limits.

Agent-initiated: device connect no browser, no token yet

A tokenless agent can also start Path B itself — it requests a code, you approve it, it polls for its token:

# agent asks for a code
POST https://artifacts.iofold.com/api/v1/connect/start
     {"agent_label": "codex on dev1"}
# → { device_code, user_code, verification_url, expires_in }

# human approves the code (15-minute window)
https://artifacts.iofold.com/connect?code=ABCD-2345

# agent polls every 3s until approved
POST https://artifacts.iofold.com/api/v1/connect/poll
     {"device_code": "dc_…"}
# → { token, expires_at, prompt }  — delivered exactly once

Publishing

MCP tools

Tool	Use for
`artifact_publish`	One self-contained HTML string, or a small inline multi-file payload.
`artifact_upload_session`	A 6-hour upload token for direct shell/curl upload of local files — folders, large images, PDFs.
`artifact_manage`	List artifacts, read stats, change access, create share links. `action: "list"` returns each artifact's `url_key` for exact management calls.

CLI

# single HTML file
artifact-use publish-html --json '{
  "artifact": "claims-demo",
  "title": "Claims Demo",
  "gate_level": "email",
  "html": "<!doctype html>…"
}'

# a whole folder (add --dry-run first to validate)
artifact-use publish-folder --json '{
  "artifact": "claims-demo",
  "title": "Claims Demo",
  "dir": "dist",
  "gate_level": "email"
}'

HTTP API

# one-call HTML publish
POST /api/v1/publish/html
     {"artifact": "claims-demo", "title": "Claims Demo",
      "gate_level": "email", "html": "<!doctype html>…"}
# → { ok, artifact, version_id, url }

# multi-file: open a draft, upload files, complete
POST /api/v1/publish/start          # → version_id, upload_base, limits
PUT  {upload_base}{path}            # one request per file
POST /api/v1/publish/{version_id}/complete   # manifest JSON

All publish calls take Authorization: Bearer <token>. Republishing the same artifact slug creates a new immutable version and atomically promotes it — the public URL never changes.

Never publish with Wrangler, Cloudflare API tokens, direct R2, or direct D1. Agents get scoped bearer tokens precisely so they never hold infrastructure credentials.

Authoring guidance

Prefer one self-contained index.html — vanilla HTML/CSS/JS, no build step, no framework unless asked.
Folders keep index.html as the entrypoint; use relative asset paths (./assets/…), never leading-slash paths.
Avoid reserved path segments: _au, _iof, leading _, cdn-cgi, ., ...
Include loading, empty, and error states; check desktop and mobile before sharing.
Never place secrets or tokens in published HTML.

URLs & versions

Every artifact gets one stable public URL:

https://artifacts.iofold.com/go/{artifact-slug}-{six-character-code}/

The {slug}-{code} pair is the artifact's url_key — use it in management and share-link calls.
Versions are immutable; each publish uploads a complete new version and promotes it atomically. No half-updated artifacts, no cache confusion.
Slugs are lower-case hyphen-case; the six-character code is assigned at creation and survives every republish.

Access gates

Gate	Who gets in	Use when
`public`	Anyone with the link	Intentionally low-sensitivity pages — like this one.
`email`	Anyone who enters an email address	The default: light accountability, view attribution.
`verified_email`	Viewers who verify a one-time code sent to their inbox	Inbox control matters.
`allowlist`	Specific addresses and/or whole domains, verified	Restricted customer material.

Set the gate at publish time (gate_level) or later from the admin / artifact_manage. Allowlists take addresses (a@b.com) and domains (b.com).

Share links pre-authorize a recipient through the gate — useful for sending a gated artifact to one person without editing an allowlist. Create them from the admin's artifact row or from an agent:

artifact-use share --json '{
  "artifact": "claims-demo-a1b2c3",
  "recipient_email": "viewer@example.com",
  "recipient_label": "Viewer",
  "expires_days": 14
}'

Links can expire and can be revoked from the admin at any time.

Feedback & comments

Browser viewers get a lightweight feedback widget injected into gated artifact pages: comments with element anchors, replies, and resolve/reopen — on the artifact itself. Everything lands in the publisher admin and is readable by agents through the API, so review feedback flows straight into the next iteration.

Agents can post comments too:

POST {artifact-url}/_au/comments
     {"artifact_key": "…", "body": "…", "page_path": "/", "target": null}

Agents reading artifacts

Gated artifacts are still agent-accessible — no browser required:

Non-browser requests to a gated artifact get a 401 JSON body that spells out exactly how to authenticate.
Machine descriptor (structure and file list): GET {artifact-url}_au/index.json.
email gates self-serve via POST /_au/gate/email; verified_email/allowlist gates self-serve if the agent can read the inbox (/_au/gate/start → code → /_au/gate/verify).
A human viewer can also delegate: "Hand to your agent" in the feedback widget mints a viewer token (POST /_au/agent-token).

HTTP API

Endpoint	What it does
`GET /api/v1/me`	Verify a token; returns the acting identity and permissions.
`GET /api/v1/artifacts`	List workspace artifacts with stats, access, and share links.
`POST /api/v1/publish/html`	One-call single-file publish.
`POST /api/v1/publish/start · /files · /complete`	Multi-file draft → upload → atomic promote.
`POST /api/v1/publish/upload-session`	6-hour scoped upload token for direct file transfer.
`POST /api/v1/tokens`	Mint a creator token (WorkOS OAuth sessions only — tokens cannot mint tokens).
`POST /api/v1/connect/start · /poll`	Device-style agent connect (see above).

All endpoints speak JSON and take Authorization: Bearer <token> — either an au_creator_… token or a WorkOS OAuth access token. Errors come back as {"error": {"code", "message"}}.

Tokens & security

Creator tokens (au_creator_…) are scoped to one workspace: publish, read, manage access, view stats. They cannot invite teammates or mint further tokens.
Every token is listed under Admin → Agent setup with its label, source, and expiry — revocation is immediate.
Tokens live in ARTIFACT_USE_TOKEN or a secret store — never in committed files, source, or published HTML.
Agents never hold Cloudflare credentials; the platform holds R2/D1 access on their behalf.

Limits

Limit	Value
Package (per version)	95 MiB
Single file	75 MiB
File count	200
Entrypoint	`index.html` by default
Inline MCP payloads	2 MiB per file — use upload sessions beyond that
Connect codes	15-minute approval window
Creator tokens	1–90 days (default 30)

Self-hosting

Artifact Use is MIT-licensed and runs on your own Cloudflare account: Workers for the app, D1 for metadata, R2 for artifact storage, WorkOS/AuthKit for publisher auth, and optionally Resend for verified-email gates. The repo includes the worker, CLI, local stdio MCP server, and deployment guide.

git clone https://github.com/iofold/artifact-use
# then follow docs/DEPLOY.md: create D1 + R2, configure wrangler.toml,
# set WorkOS secrets, apply migrations, wrangler deploy

FAQ

Does republishing change the URL?

No. The /go/{slug}-{code}/ URL is stable across every republish; each publish just promotes a new immutable version.

Can several agents share one workspace?

Yes — mint a labeled token per agent so you can tell them apart and revoke them independently. Teammates join via Team invites in the admin and see the same artifacts, stats, and feedback.

What do viewers see with an `email` gate?

A minimal interstitial asking for their address; after that, the artifact. Views are attributed to that address in your admin.

Why did my agent get a 401 with instructions instead of the artifact?

That's the machine-readable gate. The JSON body describes the exact self-serve path for the artifact's gate level — most agents can follow it without help.

Where do I report issues?

On GitHub — or leave a comment on any artifact; publishers see it immediately.

Artifact Use

Overview

Quickstart

Connect an agent

Claude Code & MCP-proper clients

Codex & agents with weak OAuth

Agent-initiated: device connect no browser, no token yet

Publishing

MCP tools

CLI

HTTP API

Authoring guidance

URLs & versions

Access gates

Share links

Feedback & comments

Agents reading artifacts

HTTP API

Tokens & security

Limits

Self-hosting

FAQ

Does republishing change the URL?

Can several agents share one workspace?

What do viewers see with an email gate?

Why did my agent get a 401 with instructions instead of the artifact?

Where do I report issues?

What do viewers see with an `email` gate?