Skip to content
Get started

SDK: Websites

A website is any web project in a folder, made with the tools the agent chooses (Astro, Vite, Next.js, VitePress, plain HTML). Its file, a JSON file in that folder listed in allyhub.yaml as kind: website (project.md), says how it is served while it is made, how it is built and where the built site is, as vercel.json's devCommand, buildCommand and outputDirectory do. Its JSON Schema is https://allyhub.com/schemas/website.schema.json.

{
"$schema": "https://allyhub.com/schemas/website.schema.json",
"dev": "astro dev --port $PORT --host $HOST --ignore-lock",
"build": "astro build",
"output": "dist"
}
Field Required What
dev no The command that serves the website while it is made, run by a shell in the website’s folder. None: output is served as it is
build no The command that builds it into output. None: it is not built
output yes The built website’s folder, from the website’s folder; . for a site of plain files

Studio runs dev by a shell in the website’s folder, with its node_modules/.bin on the PATH as npm run does (after npm install, when it has a package.json and no node_modules), with these variables set, and shows the page it serves:

Variable What
PORT The port to listen on. A dev server that listens elsewhere is never reached
HOST 127.0.0.1, the address to listen on (a server on localhost may listen on ::1 alone)
ALLYHUB_PREVIEW_HOSTS The hosts a request may name, comma-separated: in a cloud Studio, the sandbox’s and the gateway’s for that port. A dev server that checks the Host header must allow them (Next.js: allowedDevOrigins)
__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS The same hosts, as Vite reads them: Vite’s and every framework on it (Astro, SvelteKit, Nuxt, VitePress) allow them with no configuration

dev must use $PORT and $HOST itself, as Vercel’s development command uses $PORT: AllyHub adds no arguments of its own, since each framework names them differently. Studio’s server runs beside any you start yourself in the same folder: a dev server that refuses to start beside another must be told to (Astro’s --ignore-lock).

A page shows a project’s video as any page shows a video: from its files. allyhub render launch/film --type mp4,vtt,cover --out site/public --name film makes them (the video, its WebVTT captions, its poster) in the website’s public folder and prints where each went; the page uses <video> with a <track>, or any player. Render again when the video changes.

allyhub check reports AK-M013 for a website’s file that is not JSON or does not match the format. To see a page as Studio shows it, run dev with PORT and HOST=127.0.0.1 set, then allyhub frames web http://127.0.0.1:<port>/<path> --wait <ms>.

allyhub site deploy runs build here and uploads output as a private version of the website’s site, sending only the files AllyHub lacks. The first deploy writes site into the website’s file, so the folder publishes to the same site from any computer. allyhub site status lists versions.

Going public is the person’s to say. --live and allyhub site live <version> move the site only if they have let the agent update it; otherwise they answer live: false and confirm, a page for the person to say yes on: give it to them, or ask them to press Publish in Studio (Update once the site is live; for an earlier version, its row in the website’s settings). A site’s first publish is always confirmed in their browser. Taking a site offline is theirs alone, in Studio.

A hosted site is static files, index.html at the root of output:

  • /about serves about.html, /pricing/ serves pricing/index.html, and each page’s other addresses redirect to that one. The nearest 404.html answers a page not found, with status 404: nothing to configure.
  • _redirects and _headers at the root of output work as on Netlify: a real file wins over a rule that does not end in !, the default status is 301, /* /index.html 200 makes a single-page app, and a 200 rule stays inside the site. A site cannot set cookies, or the headers that are the platform’s.
  • Never published: dotfiles other than .well-known/, node_modules, the website’s file, package.json and lockfiles. A link in output is refused.
  • A file is at most 1 GiB, a version 20,000 files and 5 GiB. Range works, so video plays from a page, Safari’s included.
  • Every file is revalidated by its digest. Files a framework names by their bytes are kept by browsers only if _headers says so: /_astro/* then Cache-Control: public, max-age=31536000, immutable (or /assets/* for Vite, /_next/static/* for Next.js).
  • A site stays out of search engines until the person allows it.

build is the website’s own; its output is a standard static folder that deploys anywhere (Vercel, Netlify, Cloudflare). Check it with the industry’s tools: lychee for links, Lighthouse CI for search, accessibility and performance, and the framework’s own check.

Was this page helpful?