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 creates the artifact, then publishes the files:

create_service
{ "kind": "site", "name": "report" }

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; }" }
  ]
}

With files, publish_site carries the pages in the call, as text only: HTML, CSS, JavaScript, Markdown, JSON and SVG. An agent that can run git publishes from a Git push instead, which sends only what changed and carries any file, images and PDFs included. See Publish with Git.

With the CLI, valet sites create makes the artifact and links the current folder to it. valet deploy commits every file in the folder except .git and .valet, then pushes the commit with Git, sending only what changed. It doesn't use ignore files to exclude files. 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.

Valet serves files as follows:

• /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.

A blocking release policy can refuse a release. The artifact keeps serving its current release. See Release policies to review findings in the dashboard's Releases tab.

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" }

An agent that can run git clones the artifact instead, through create_push or get_source with git: true, and publishes its changes from a push.

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.

Show who is visiting#

A published page can ask Valet who opened it. It sends a GET request to /__valet/visitor on its own address. The answer is JSON: a visitor object with the visitor's kind, sub, email and name, and a signed token.

Use it to greet a signed-in member or to show which address a share went to. Don't use it to protect data. A visitor controls the page in their own browser, and Valet already checks access before it serves the page. To keep data behind who someone is, build an app.

Limits#

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

Next steps#

• Data access: choose how your artifact reaches company data.
• Apps: run server code or store records.