Creating Surfaces
Build a surface with your coding agent, or upload an HTML file from the web app.
A surface is one self-contained HTML file. There are two ways to create one: have your coding agent build and publish it, or upload a file yourself at traces.com/surfaces/create.
Build a surface with your agent
The marketplace and the create page both have a Start building your surface with your agent section with two buttons:
-
Copy prompt copies a prompt to paste into your coding agent. It points the agent at the surface-building guide and tells it to publish through Traces MCP:
Read & follow https://traces.com/surfaces.md to start build a surface. Use the traces mcp to publish and manage it. Follow https://traces.com/docs/mcp to install it. -
Download skill downloads the same guide as a
SKILL.mdfile, for agents that load skills from disk.
Neither button requires signing in. Add a sentence to the prompt describing what the surface should show, and connect Traces MCP so the agent can upload it. See Surfaces with MCP for the upload and release flow the agent follows.
Upload a surface in the web app
Click Upload a surface on the marketplace, or Create in a trace page's surface picker, to open /surfaces/create. You need to be signed in.
Fill in:
| Field | Notes |
|---|---|
| Icon | Shown on the surface's tab and card. |
| Title | The surface's display name. |
| ID | The surface's key, used in URLs like /surfaces/<key> and ?surface=<key>. Globally unique and permanent after creation. |
| Description | Optional. Shown on the marketplace card and the surface's page. |
| Surface HTML | A single .html file, up to 16 MiB. |
| Namespace | The personal namespace or organization that will own the surface. |
| Who can use this surface? | Just for me (personal namespace) or Just for my team (organization) keeps it private to the namespace. Everyone lists it in the marketplace. |
Click Create surface, or Create & publish surface if you chose Everyone. The file becomes version 1.0.0 and the surface's current version, and you land on the surface's page.
Only organization admins and owners can make a surface public. Members can create private surfaces and ask an admin to publish them. See who can do what.
What a surface file can contain
Surfaces run in a sandboxed frame, so the file must be fully self-contained:
- One HTML file with a
<head>element, up to 16 MiB, with all CSS and JavaScript inline - No external resources: no
<link>,<iframe>,@import, CDN scripts, web fonts, or remote images. Usedata:URIs or inline SVG instead - No network access.
fetch,XMLHttpRequest, WebSockets, and form submission all fail - Data comes from one call,
await window.traces.getTrace(), which returns the trace the surface is open on
The full contract, including the trace data shape and design guidance, is in the surface-building guide.