Artifacts

Artifacts are live, interactive applications that agents create and render directly on the board canvas. An agent scaffolds a small app via MCP, writes code into it, and you see it running — no deploy, no preview URL, no context switching.

Under the hood, artifacts are powered by Sandpack, the open-source in-browser bundler by CodeSandbox. A directory of source files inside the worktree gets compiled and rendered live in the browser — no server-side build step needed. The agent writes code, the board shows the result.

How it works

1. Agent creates an artifact via agor_artifacts_create — picks a template (React, vanilla JS, etc.), names it, and optionally provides initial files
2. Agor scaffolds the directory at .agor/artifacts/<id>/ inside the worktree, writes a sandpack.json manifest and source files
3. The artifact appears on the board as an interactive node with a live Sandpack preview
4. Agent edits files using normal file tools, then calls agor_artifacts_refresh to push changes to the board
5. You interact with the running app directly on the canvas — click buttons, fill forms, see state updates

Artifact anatomy

Each artifact is a filesystem directory plus a database record:

On disk (inside the worktree):

.agor/artifacts/<artifact-id>/
  sandpack.json        # Manifest: template, dependencies, entry point
  App.tsx              # Source files (varies by template)
  styles.css
  ...

On the board:

• Header — Artifact name with an interact toggle (eye icon)
• Preview — Live Sandpack renderer showing the running application
• Interact mode — Toggle to interact with the app (click buttons, type inputs) vs. normal canvas navigation

Use cases

The possibilities are genuinely endless. Artifacts are a general-purpose way for agents to express themselves visually and interactively — any time you need something rendered, an artifact can do it.

The key advantage over having an agent build a regular app in a folder is that it’s right there on your board. No deploy step, no preview URL, no context switching. You ask for a change, the agent writes code, and you see the result update live. It’s the tightest iteration loop you can get.

If you’ve used artifacts in Claude Desktop or ChatGPT Canvas, the concept is similar — rich interactive windows embedded in your conversation. But here they live on a multiplayer spatial canvas where multiple agents and humans collaborate side by side.

The most basic use case is anything where you need visual feedback during agent collaboration. Writing an article and want to see it rendered? Building a form and want to click through it? Sketching a chart and want to see the data? If you need to see it while you work on it, artifacts are the answer.

Custom data visualization

This is the killer app. Things that would take a D3.js expert days, an agent can scaffold in minutes.

• Interactive dashboards — Real-time charts, metrics, and KPIs rendered live on the board. Ask “show me API latency by endpoint” and watch it materialize.
• Data explorers — Filterable, sortable tables with search. Feed in a dataset and get an interactive viewer instead of squinting at terminal output.
• Network and graph visualizations — Force-directed graphs, dependency trees, org charts. Complex visual structures that are nearly impossible to convey in text.

Developer tools

• Live component playground — Iterate on a React component with your agent and see changes instantly. Like a mini Storybook embedded in your board.
• API playground — A form-based endpoint tester with response viewer. Build one per service your team works with.
• Schema and architecture visualizer — Interactive ER diagrams, service topology maps, data flow diagrams. Turn abstract architecture into something you can point at.

Design iteration and prototyping

• UI mockups — “Sketch me a settings page for feature X” produces an interactive prototype right on the board, not a static screenshot.
• Content authoring — Write a blog post, doc page, or marketing email with your agent and see it rendered live as you iterate. The most natural artifact use case.
• Landing page drafts — Quick marketing page iterations without touching production. Get stakeholder feedback before a single line hits your real codebase.

Business operations

Artifacts are not just for developers. Any role that needs a custom, purpose-built UI can get one in minutes.

• Contract redline viewer — Legal gets an interactive diff showing proposed changes with accept/reject affordances, instead of emailing Word docs back and forth.
• Deal calculator — Sales gets a pricing configurator with sliders for seats, tiers, and discounts, showing ARR impact in real time.
• Compliance checklist — Ops gets an interactive onboarding tracker for a specific customer implementation, tailored to exactly what that deal requires.
• Customer health scorecard — CS gets a single-page view pulling data from multiple sources that no single SaaS tool provides.

Ephemeral SaaS alternatives

When you need a custom workflow but your existing tools (HubSpot, Salesforce, Jira) are too rigid for the situation:

• Custom approval forms — Replace a 15-click SaaS workflow with a purpose-built form that does exactly what you need.
• Cross-tool aggregator — Pull data from CRM, usage metrics, and support tickets into one unified view.
• QBR and report builder — Agent pulls metrics from multiple sources and renders presentation-ready charts. No more copying numbers between tabs.
• Release notes generator — An interactive editor that pulls from git log and PRs, letting you format customer-facing comms without context switching.

Templates

Artifacts support several Sandpack templates:

Agents can also provide custom files and dependencies at creation time — the template just determines the default scaffold.

MCP tools

Agents manage artifacts through Agor’s MCP tools:

The typical agent workflow: create the artifact, edit files with standard file tools, check build to verify structure, then refresh to push changes live.

Interacting with artifacts

Artifacts live on the React Flow canvas, which means mouse events need careful handling:

• Default mode — Canvas zoom/pan/drag works normally over the artifact. The preview is visible but non-interactive
• Interact mode — Click the eye icon in the header to enable direct interaction. Mouse events pass through to the iframe so you can click buttons, scroll, and type

This toggle prevents the iframe from capturing canvas navigation while still letting you use the running app when needed.

Managing artifacts

Settings > Artifacts provides a management view for all artifacts across the instance. From there you can:

• View artifact metadata (name, template, build status, worktree, board)
• Edit name and description
• Delete artifacts (removes filesystem directory, board placement, and database record)

Artifacts are created exclusively by agents via MCP — there’s no manual creation UI. The Settings table is for oversight and cleanup.

Beyond frontend

Sandpack’s Nodebox runtime can execute Node.js code directly in the browser, with out-of-the-box support for frameworks like Next.js, Vite, and Astro. This means artifacts aren’t limited to pure client-side apps — you can prototype lightweight full-stack patterns too. The main limitation is that Nodebox can’t access raw sockets, so native database drivers (Postgres, MySQL, MongoDB) won’t work in-browser.

For anything that needs a real backend, the artifact is still a great starting point — the code is just files in a directory.

Secrets and API credentials (agor.config.js)

Artifacts can securely access API keys and credentials through a convention-based config file. If an artifact contains a file named /agor.config.js, Agor treats it as a Handlebars template and renders it per-user at view time. This means each user’s secrets are injected privately — the raw template on disk only contains placeholders, never actual values.

How it works

The agent writes an agor.config.js file with template variables:

// agor.config.js — template on disk (no secrets here)
export const apiKey = "{{user.env.OPENAI_API_KEY}}";
export const apiUrl = "{{agor.apiUrl}}";

When you view the artifact, Agor renders the template with your environment variables. The artifact code imports from it like any JS module:

import { apiKey, apiUrl } from '/agor.config.js';
 
// apiKey is your personal key, resolved at view time
const res = await fetch('https://api.openai.com/v1/chat/completions', {
  headers: { Authorization: `Bearer ${apiKey}` },
  // ...
});

Available template variables

Setting up your environment variables

1. Go to Settings > Environment Variables
2. Add the keys your artifacts need (e.g., OPENAI_API_KEY, GITHUB_TOKEN)
3. Values are encrypted at rest with AES-256-GCM — they’re only decrypted when rendering your config

If a referenced variable isn’t set, it renders as an empty string. Well-written artifacts check for this and show a helpful message instead of failing silently.

Security properties

This design has a meaningful security advantage over tools like Claude Desktop artifacts, where secrets are typically pasted into the conversation and become part of the LLM context:

• Secrets never hit the LLM — The agent writes {{user.env.OPENAI_API_KEY}} as a placeholder. Your actual API key is resolved server-side at view time and never appears in conversation history or model context
• Per-user isolation — Two users viewing the same artifact each get their own rendered config with their own keys
• Template is transparent — The raw agor.config.js on disk only contains placeholders, so anyone reviewing the artifact code sees which credentials are needed without seeing the actual values
• Encrypted at rest — User environment variables are stored with AES-256-GCM encryption

From prototype to production

Artifacts are designed for rapid prototyping, not permanent hosting. When you’re ready to ship, the graduation path is straightforward:

1. The code is already on disk — artifact source files live at .agor/artifacts/<id>/ inside your worktree. They’re standard source files, not a proprietary format
2. Ask your agent to scaffold a real project — “Take this artifact and set it up as a Next.js app” or “Create a Vite project from this prototype”
3. Pick your hosting — Vercel, Netlify, Cloudflare Pages, a Docker container — the agent can set up deployment config for whatever platform you choose
4. Graduate your secrets — Move agor.config.js template variables to your hosting platform’s environment variable system (Vercel env vars, .env files, etc.)

The artifact gets you from idea to working UI in minutes. The agent gets you from prototype to deployed app when you’re ready.

Sandpack and CodeSandbox

Sandpack is the open-source in-browser bundler that powers artifact rendering. It’s built and maintained by the team at CodeSandbox, who also offer a full cloud development platform with collaborative VMs, instant environments, and team features. Sandpack itself is free and open-source (MIT licensed) — Agor uses the @codesandbox/sandpack-react package.

Security

Artifact filesystem operations include containment guards:

• Path traversal protection — All file paths are resolved and validated to stay within the worktree boundary
• Symlink filtering — Symbolic links are skipped during file enumeration to prevent filesystem escape
• Browser sandboxing — Artifacts render in Sandpack’s in-browser bundler, isolated from the host

Related docs

• Agor MCP Server — The MCP tools agents use to create and manage artifacts
• Cards — Another board primitive for non-code workflow entities
• Assistants — Persistent agents that can create artifacts as part of their work