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 compact agent handoff, and paste it to any agent. The agent follows the matching harness guide in /llms.txt.

Overview

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

Agents publish over hosted MCP — single HTML files or complete folders with images, data, and PDFs. CLI, local stdio MCP, and plain HTTP remain available as advanced fallbacks. 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 comments 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 Connect an agent. It contains one scoped creator token and a short reference to /llms.txt.
Paste it to your agent — Claude Code, Codex, or another MCP client. The agent identifies its harness and follows exactly one matching auth path.
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

The admin gives you one compact, harness-neutral handoff. The creator token appears once; setup details stay in /llms.txt so the agent can select the right path for its current harness.

Codex desktop · CLI · IDE

One shared OAuth connection

These Codex surfaces share MCP config and OAuth credentials on the same host. In the ChatGPT desktop app, open Settings → MCP servers → Add server. Name it artifact-use, choose Streamable HTTP, and enter the hosted MCP URL. Then select Save → Restart → Authenticate and confirm with /mcp.

# CLI equivalent
codex mcp add artifact-use --url https://artifacts.iofold.com/mcp
codex mcp login artifact-use

Remove any existing bearer_token_env_var before OAuth because Codex tries a configured bearer before stored OAuth. Do not use the creator token on this path.

Codex CLI fallback · Bearer

Only when OAuth is unavailable or unreliable

Export the supplied token in the terminal that will launch Codex, replace the URL-only entry with bearer auth, then restart Codex from that same terminal.

# launcher terminal, before Codex starts
export ARTIFACT_USE_TOKEN='au_creator_…'
codex mcp remove artifact-use
codex mcp add artifact-use \
  --url https://artifacts.iofold.com/mcp \
  --bearer-token-env-var ARTIFACT_USE_TOKEN
codex

An export inside an already-running Codex shell cannot change the parent Codex process environment.

Claude Code · OAuth

Authenticate from `/mcp`

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

Do not use the creator token on this path.

Other clients

Prefer OAuth, bearer as fallback

Configure the hosted MCP URL and use OAuth when supported. If the client cannot complete OAuth, use the supplied creator token as its bearer credential. Configure one auth mode, not both.

Why keep the handoff short? Harness-specific setup can evolve in /llms.txt without minting a longer prompt or repeating its secret. Agents can read /llms-full.txt for the complete publishing rules and limits after connecting.

Advanced: agent-initiated device connect no browser, no token yet

A tokenless agent can request a code, ask you to approve it, then poll 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/admin/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, move an artifact to another of your workspaces (`action: "move"` with `to_workspace`; URL unchanged), or permanently delete one (`action: "delete"`, requires `confirm: true`). `action: "list"` returns each artifact's `url_key` for exact management calls.
`artifact_comments`	List, reply to, resolve, or reopen comment threads.

Hosted MCP is the normal path. The CLI, direct HTTP API, and bundled local stdio MCP server are advanced alternatives for harnesses without hosted MCP support and specialized shell workflows.

Advanced: 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"
}'

Advanced: 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 direct HTTP 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.

Comments

Browser viewers get a lightweight comments 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 fully readable and writable by agents through the API, so review comments flow straight into the next iteration.

The publisher's agent closes the loop with the workspace token it already holds — the artifact_comments MCP tool, artifact-use comments in the CLI, or plain HTTP:

# which artifacts have open comments? (open_comments per artifact)
GET /api/v1/artifacts

# read open threads (filters: status, since, page_path, limit)
GET /api/v1/artifacts/{url_key}/comments?status=open

# reply to a thread, then resolve it
POST  /api/v1/artifacts/{url_key}/comments   {"body": "Fixed in v2.", "parent_id": 42}
PATCH /api/v1/artifacts/{url_key}/comments   {"id": 42, "resolved": true}

Viewer-side agents (delegated via "Hand to your agent", or self-served through the gate) use the same shapes on /_au/comments with artifact_key:

GET   /_au/comments?artifact_key={url_key}&status=open
POST  /_au/comments   {"artifact_key": "…", "body": "…", "parent_id": 42}
PATCH /_au/comments   {"artifact_key": "…", "id": 42, "resolved": true}

Posting returns the created comment with its id, replies thread via parent_id, and anchored comments carry a target object describing the on-page element. Fix, republish the same slug, reply, resolve — the reviewers' link never changes.

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 comments 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, share links, and open-comment counts.
`GET · POST · PATCH /api/v1/artifacts/{url_key}/comments`	List comment threads (status/since filters), reply or comment, resolve/reopen.
`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 → Connect an agent 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, Cloudflare Email Sending for verified-email gates, and WorkOS/AuthKit for publisher auth. 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 comments.

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.