Build

Artifacts

What an artifact is#

An artifact is a static website: HTML, CSS, JavaScript, images and any other files, published from a folder. Reports, dashboards, briefs, prototypes and slide-like pages are all artifacts. Everything runs in the visitor's browser; there is no server code. If your tool needs a server, publish it as an app instead.

The CLI and the MCP tools call an artifact a site: valet sites, publish_site.

Publish an artifact#

Ask your agent:

Publish this report as a Valet artifact called report.

Your agent publishes the files:

publish_site
{
  "name": "report",
  "title": "Weekly support report",
  "description": "Tickets opened and closed this week, by team.",
  "files": [
    { "path": "index.html", "content": "<!doctype html>\n<title>Weekly support report</title>\n…" },
    { "path": "style.css", "content": "body { font-family: system-ui; }" }
  ]
}

publish_site carries the files in the call. It takes text files only: HTML, CSS, JavaScript, Markdown, JSON and SVG. Images, PDFs and other binary files need the CLI.

With the CLI, valet sites create makes the artifact and links the current folder to it. valet deploy uploads every file in the folder except .git and .valet. It reads no ignore file (a list of files to leave out), so publish from a folder that holds only what belongs on the page.

Addresses#

Every artifact has its own address:

https://<name>.<org>.valet.run

An artifact named report in the organization acme serves at https://report.acme.valet.run. If you don't choose a name, Valet generates one. Artifacts, apps and agents share one set of names in an organization, so two can't have the same name.

In a new organization, the first address can take a few minutes to start working while Valet sets up HTTPS.

A few serving rules:

• /about serves about.html, and /about/ serves about/index.html.
• A missing page serves your 404.html if the artifact has one.
• An artifact answers only page requests. A form that posts to the artifact's own address gets an error; use an app for that.

Who can open it#

Each artifact has one access mode. New artifacts are private.

Ask your agent:

Make the report public.

set_service_access
{ "name": "report", "kind": "site", "mode": "public" }

For password mode, set_service_access takes the password as an argument, so the password appears in the conversation. To keep it out, run valet sites access report password, which asks for the password without showing it, or set it in the dashboard.

A sign-in to an artifact lasts 24 hours. Changing or clearing the password signs out everyone who entered the old one.

Share with one person#

Sharing gives one person access to one artifact. They don't need a Valet account, and they get nothing else your organization owns. Use it to show a private report to a customer or a colleague outside your organization.

Valet emails each person a link. The link itself grants access: anyone who has the email can open the artifact, so forwarding it forwards access. A share link lasts until you remove it, unless you set a deadline when you send it.

share_service
{ "name": "report", "emails": ["alice@example.com"], "expires_in": "7d" }

• expires_in (--expires-in in the CLI) stops the link a set time after you send it.
• access_ttl (--expires-after-open) stops it a set time after the person first opens it.
• You can share with up to ten addresses at a time.

To remove access:

unshare_service
{ "name": "report", "emails": ["alice@example.com"] }

Access ends within seconds. A removed link never works again; sharing with the same address sends a new one.

valet sites shares report lists who has access and whether they have opened it; no MCP tool does. In the dashboard, an artifact's Sharing tab shows the same list and can renew an expired link.

Update, rename or remove#

Publishing again replaces the artifact's files with a new release. The address stays the same. Valet removes any file you leave out of the new publish.

Any member of the organization can update an artifact, even without the original files. Your agent reads the published files first:

get_source
{ "name": "report" }

To rename or remove it:

rename_service
{ "name": "report", "new_name": "q3-report" }

destroy_service
{ "name": "q3-report" }

Renaming moves the artifact to the new address. The old address stops working and doesn't redirect. Destroying an artifact takes it down permanently and removes every share link.

Call your organization's connectors#

A page can use live data from a connector your organization has set up, such as a CRM or an internal MCP server. Valet adds the organization's credential, so the page never holds it. Ask your agent:

Attach the hubspot connector to the report and show this week's deals.

The agent attaches the connector:

attach_connector
{ "name": "report", "connector": "hubspot" }

Then it reads the connector's tools with list_connector_tools, and runs one tool call with call_connector to see what comes back. That call is real: a tool that writes or sends does so.

Your agent then writes the page's code to call the connector through Valet.

Connector limits:

• The connector must be an MCP server Valet reaches over HTTP. list_connectors shows which ones qualify.
• Public artifacts can't call connectors. Make the artifact private or password first.
• By default, each artifact can make 60 connector calls a minute. Each call has 30 seconds and a 4 MiB answer limit.

See Connectors for how an administrator sets connectors up.

Limits#

The CLI publishes any file type. An artifact can't run server code, store data from visitors, or hold env vars or resources; those need an app.