Publishing

Publishing builds the site's source and puts the output live.

What a deployment is

A deployment is one set of files, with the commits it was built from. It has a status, and when it goes live it has an address.

A site has at most one live deployment. Activating a new one supersedes the last.

Two ways to publish

• POST /v1/sites/{id}/publish builds the source and activates the result. This is what an agent uses.
• The manifest flow uploads files the agent already has, with no build. Read The publish contract.

Scope

A publish has a scope.

• site builds the head of both repositories. This is the default.
• posts builds the live site's own commit with the posts as they are now.

posts is what lets a post go live while a redesign sits half done.

It also changes what a build failure means. A posts publish builds the live site's commit, so a change you just made to the site's code is not in the tree that failed. The compiler blames a version you are not looking at, and Clave says so in the message.

The build

Clave builds the source in a sandbox of its own, used for one build and then destroyed. The sandbox runs the site's own code — astro.config.mjs and every component's frontmatter — so it holds nothing worth stealing.

The build can read from the network only to get fonts: Google Fonts and Fontsource, through Astro's fonts API. The build downloads the font files, and the site serves them from its own address, so a visitor never contacts Google. Any other request fails, and the build log names the address that was refused.

A build failure carries a detail field with the build log. That log is the compiler telling whoever wrote the source what is wrong with it. It is the only place a detail field appears.

A failure of any other kind is Clave's, and it carries no build log.

Restore

Clave keeps every byte it ever published. A restore is one call and needs no upload: POST /v1/deployments/{id}/restore puts an earlier deployment back on the address.

That is what makes the archive worth holding. Cloudflare serves the files; Clave holds them.

The badge

A live site shows a small "Made with Clave" link at the bottom left. Clave adds it as the page is served, so it is not in your source and not in what Clave archives. Its owner turns it off with "badge": false in the site's clave.site.json. See Site settings.

What happens if Clave is down

A published site is served by Cloudflare and does not depend on this API. An outage here stops deploys and reads. It does not take a site down.