Signal Roads
Building a Website with Agents · Lesson 2 of 6

How to set up an Astro site with an AI agent

Turn an empty folder into a real multi-page project. What Astro is and why we pick it, what running locally means, and the agent setting the site up.

In Foundations you had the agent build a single page inside a folder. Now it sets up a whole project: several pages that share one design, with room to grow into as many as your site ever needs. Think of it as the skeleton the real site hangs on.

We slow down for two ideas only: what Astro is, and what running a site locally means. The agent handles all the mechanics; the plain version of each idea is so you are never looking at something on your screen with no idea what you are seeing.

What Astro is

Astro
A free, open tool for building websites out of plain files. You describe the pages and Astro turns them into a fast, ordinary website that any host can serve. Nothing about it is tied to one company or locked behind a login.

It builds your site down to plain HTML, about as light as the web gets, which makes it easy to keep fast and cheap, often free, to host. Search engines read it without a fight. And an agent is at home in it, because underneath, the site is just files it can open and change.

I teach Astro because it stays the simplest for what we are building, and because nothing you learn here is locked to it. Plenty of other tools could build a site like this one, and Astro’s own site makes the fuller case if you want to look closer.

What “running locally” means

Before your site is ever online, it runs on your own computer. That is what running locally means.

When the agent starts your site, it opens a dev server: a small program that runs the site on your computer. The site appears in your browser at a private address like localhost:4321.

Localhost
A web address that exists only on your own computer. localhost:4321 is your site, live and clickable, but visible to no one but you. Nothing is on the internet yet.

The useful part is that it updates the moment anything changes. The agent edits a page, you glance back at the browser, and the change is already there. And because it is all private, this is your workshop: you can try things, break them, and redo them, with no half-finished site ever out where people can see it.

The agent sets up the Astro project

The whole setup is a single instruction to the agent, and you do not even need to make a folder for it first. Open your editor the way you did when you set it up in Foundations.

Assignment: scaffold your Astro site

Copy this as is, since we build the same four pages together. Give the folder any name you like when it asks, and approve the install commands, which are just Astro and its dev server arriving. The prompt also carries two habits over from Foundations: your context file comes along so the agent reads it here too, and version control goes on from the first minute.

Set up a new Astro site in its own new folder. Give it one shared layout and four pages: Home, About, Work, and Contact. Leave them mostly blank for now, just a heading and a line of placeholder text on each, so I can see the structure. Copy my context file into the new folder so you read it there too; if I do not have one, say so and carry on. Set up version control with .env and secrets ignored, and take a first checkpoint. Then start it running so I can preview it in my browser.

When it is done, that new folder is a real project. I named mine first-site-demo, and gave its pretend owner a name, Jane Doe, so the demo pages have someone to belong to. Hover or tap the marks to see what each part does:

first-site-demo/
├── public/Files served exactly as they are, like your photo or logo.
├── src/Short for source. Everything you build lives in here.
│   ├── layouts/The design every page shares, the header, footer, and frame around your content. That is Layout.astro.
│   │   └── Layout.astroThe layout file itself. You set the shared header, footer, and page frame here once.
│   ├── pages/One file per page, and the file name becomes the web address.
│   │   ├── index.astroYour home page. index is the page at the site’s root, the front door.
│   │   ├── about.astroYour About page, at /about.
│   │   ├── work.astroYour Work page, at /work.
│   │   └── contact.astroYour Contact page, at /contact.
│   └── styles/How the site looks, the colors, fonts, and spacing, kept in global.css.
│       └── global.cssThe stylesheet itself, where the site’s colors, fonts, and spacing live.
├── astro.config.mjsAstro’s own settings. You will almost never open it.
└── package.jsonThe list of tools the project uses. The agent keeps it up to date.

The layout is the part worth pausing on: the single design all four pages share, so you edit the header once and it changes everywhere. That is the thing a page builder makes you rebuild by hand, page after page.

Running, at that localhost address:

localhost:4321

That is a real website, running locally. You can click Home, About, Work, and Contact, and the pages change. There is nothing on it yet, no photo, no words that are yours, and for right now that is exactly as it should be.

What you have now

The empty folder is gone. In its place is a running, four-page site you can open in your browser, built on a layout you will only have to design once. Stopping here, with the structure standing, lets you see the whole shape of the site before a single word of it is yours. Next lesson we get your material into the folder and start turning these four blank pages into your site.