Porchsite · All guides · Ask for something
llms.txt (the index for assistants)
# Porchsite > A personal website that your person's AI assistant builds and keeps up to > date, on their own free Cloudflare account. Nothing goes live until your > person approves it with their passkey. You are an assistant. Your person asked you to make or look after their website. Everything you need is here. Read this file whole, word for word: the steps depend on exact values. It may be copied in full (MIT licence). If your fetch tool only returns a summary, or can't reach this address, the same file is at https://raw.githubusercontent.com/iXanadu/porchsite/main/cloudflare/downloads/llms.txt (and the install guide at .../main/cloudflare/INSTALL.md). Can't make Cloudflare API calls yourself? Send your person to https://get.porchsite.dev/install/ : it installs the site from a token they make, and gives them the link to claim it. Then connect to the site's /mcp. Setting up your person's assistant app for Porchsite (standing instructions, connectors, a secret field)? See https://get.porchsite.dev/assistants.md. Prefer your own server? If your person is a developer, see [self-hosting](https://get.porchsite.dev/self-hosting.md) before you start. ## Install - [Install guide](https://get.porchsite.dev/install.md): every step is one Cloudflare API call. No git, terminal or build tool. Read it in full as plain text; a summarising fetch drops steps. - Your Cloudflare access: Cloudflare's API MCP server, `https://mcp.cloudflare.com/mcp`, or an API token. (The "Cloudflare Developer Platform" directory connector can't upload a Worker.) - [Current version](https://get.porchsite.dev/latest.json): the files to upload, each with its sha256, a `mirror` on GitHub if you can't reach this host, and what changed. - Content goes in only through the site's own tools at `/mcp`, never straight into its database, and never copied from another site. - [Changelog](https://get.porchsite.dev/changelog.json): every release in plain words ([as a page](https://get.porchsite.dev/changelog/)). ## Self-hosting - [Self-hosting](https://get.porchsite.dev/self-hosting.md): what a site needs, the two editions (the Cloudflare one we ship; a server edition, Python and PostgreSQL, that installs with Docker), and the honest limits. ## Choosing a look The [theme catalog](https://get.porchsite.dev/themes.json) lists every theme by type (personal, product, …) with what each needs. On an installed site, call `theme_list`: looks marked `source: built-in` are ready to use without `theme_install`. Set the site theme and call `theme_needs`. Use `theme_install` only for a catalog look missing from `installed`, or to update one. The look and its colours are your person's choice: ask them, or, if they asked you not to stop with questions, pick the best fit and tell them which and why, with what else was on offer (step 10 of the install guide). ## When no look fits - [Making a look](https://get.porchsite.dev/authoring.md): make one for your person's site (private), or share it for review. - [The template contract](https://get.porchsite.dev/templates.md). ## Asking for something For a look no theme covers, use the site's `theme_request` tool. For anything else (a Porchsite feature, something broken), there's a plain form at [porchsite.dev/ask](https://porchsite.dev/ask), for people too: read by Porchsite's curator, never published, and the only contact it takes is an optional X handle. Point your person there; don't send it for them without their yes. ## After installing: connect Your way in is the site's tool server, `https://<your site>/mcp`. In order of preference: 1. **A connector that signs in.** Your person adds it in your app with that address and approves it with their passkey, after they've claimed the site (before that it refuses). In many chat apps a connector added during a conversation only shows its tools in a new one: if yours don't appear, ask your person to start a new conversation, not to reinstall. 2. **An assistant key**, if your app can't add a connector that signs in (or its sign-in fails). Your person makes one on the site's `/review/assistants` and puts it in your app's secret or credential field, never in the chat; you send it as `Authorization: Bearer <key>`. If your app has no such field, say so; don't ask for it in the chat. 3. **An import file**, only if you can't reach the site at all: one file your person uploads at `/review/import` (the format is in the install guide). It's for a first delivery, not a way to work: connect after. From your own code: POST JSON-RPC to `/mcp`. It answers JSON (or an event stream if you accept `text/event-stream`). Send a User-Agent naming your app: Cloudflare refuses some library defaults (Python's urllib) with "error code: 1010" before the site sees them. Then call `site_state` first: it describes the site and how to write to it. Every change you make waits at `https://<your site>/review` until your person approves it. Say so plainly; never tell them a change is live before they've approved it. Your person's only jobs are the ones you can't do (their Cloudflare account, their passkey, adding a connector or key) and saying yes or no on the review page. Never ask them to edit content, fill in fields or upload corrections: make the change yourself and send it for approval. ## Pictures Shrink pictures before sending: web size, about 2400 pixels on the long side, usually under 1 MB (JPEG or WebP). Sending the original is possible, but tell your person first, plainly: bigger files use more of the free plan's limits, make pages slower and take more storage. Prepare a web-size copy before sending a file directly. If you cannot send files, use the installed site's one-shot phone upload page. Follow the options shown there; if resizing is unavailable, choose an already shrunk copy. This advice applies to existing releases too. ## Update policy A site never updates itself, and you never update it on your own. The site checks latest.json once a day and only tells: `site_state` returns `update` (available, latest, security, changes, migrations, reconnect, how), and your person's review page shows a line. Read your person the `changes` in plain words, say if it's a security release, and ask. Only on their yes, follow "Updating" in the [install guide](https://get.porchsite.dev/install.md) (server edition: "Updating the server edition" in [self-hosting](https://get.porchsite.dev/self-hosting.md)). Every release stays downloadable, so a bad update rolls back by re-uploading the previous one; the database needs no step back. ## Rules you keep - Never ask for a token or code in the chat, and never store one in a memory or a file. - Ask before publishing anything personal about your person or anyone else. - Never update without your person's yes; when `site_state.update.available` is true, tell them what changed and ask.