# Lobsite docs

## Quick start

In a built project, run one command. No account needed: the site lasts 6 hours unless you log in and claim it.

```sh
npx lobsite
```

The folder is the argument, `dir` in lobsite.toml, or the first of `dist/`, `build/`, `out/`, `_site/`, `public/`. Only files that changed upload.

## AI agents

Coding agents (Claude Code, Cursor, Codex and others) deploy with the same command. Under an agent the CLI never asks a question, and its output ends with a "Tell the user:" line with the URL and, for a site without an account, the claim link that keeps it.

```sh
npx -y lobsite --yes
```

There is also an MCP server for coding agents, a remote one for ChatGPT and Claude.ai, and a curl command for sandboxes without Node. [Set up your agent](https://lobsite.com/docs/agents).

## Drag and drop

Sign in and drop a folder or a zip anywhere on the dashboard. The same checks run before anything uploads; secret files are always left out.

## lobsite.toml

```toml
site = "quiet-fox-4821"
dir  = "dist"
spa  = false            # true: paths that aren't files open index.html

[[redirects]]
from   = "/blog/:slug"
to     = "/posts/:slug"
status = 301            # 301 | 302 | 307 | 308

[[headers]]
for = "/assets/*"
[headers.values]
Cache-Control = "public, max-age=31536000, immutable"

[forms.contact]
required = ["email", "message"]
redirect = "/thanks"
```

Unknown keys are an error, with the closest valid key suggested. The config travels with each deploy, so a rollback restores it.

## Single-page apps

Apps with client-side routing, such as React Router, Vue Router or TanStack Router, have one `index.html` and draw every page in the browser. Opening `/dashboard/settings` directly, or reloading it, asks the server for a file that doesn't exist. Single-page mode answers those paths with your `index.html`, so the app's router takes over. There are three ways to turn it on:

- **`spa = true` in `lobsite.toml`.** It travels with each deploy, so a rollback restores it. Needs lobsite 0.1.8 or newer; older versions stop with "Unknown key".
- **Single-page app in the site's settings** in the dashboard. It's the way for sites you drag and drop, since a dropped folder doesn't send a `lobsite.toml`. It's a site setting, so it stays as it is through deploys and rollbacks.
- **A `200.html` at the top of the site.** It's served instead of `index.html`, and works with any CLI version and with drag and drop. This is how Surge does it.

With Vite (React, Vue, Svelte or Solid), add the setting and deploy `dist/` as usual:

```sh
npm run build
npx lobsite
```

Only page requests get the app: a path whose last part has no extension (`/dashboard`, `/users/42`), or any request from a browser asking for HTML (`/users/jane.doe`). A missing file such as `/assets/index-3f9a.js` gets a real 404. That matters right after a deploy: a visitor who still has the old version open gets a clear error for the old script, not your HTML in its place.

| The site has | A missing page (`/dashboard`) | A missing file (`/old.js`) |
|---|---|---|
| nothing | Lobsite's "Not found", 404 | Lobsite's "Not found", 404 |
| `404.html` | `404.html`, 404 | `404.html`, 404 |
| single-page mode | `index.html`, 200 | Lobsite's "Not found", 404 |
| single-page mode and `404.html` | `index.html`, 200 | `404.html`, 404 |
| `200.html` (with or without the setting) | `200.html`, 200 | `404.html` if there is one, else "Not found", 404 |

Coming from Netlify, the `_redirects` rule `/* /index.html 200` is `spa = true`; from Vercel, a rewrite of `/(.*)` to `/index.html` is the same.

## .lobsiteignore

Files that match a pattern in `.lobsiteignore` aren't deployed. The syntax is the same as `.gitignore`:

```text
drafts/
*.psd
/notes.txt
!keep.psd
```

The file is read from the deployed folder and from the project root (next to lobsite.toml); patterns in the root file are relative to the root. `.git`, `node_modules`, `.DS_Store` and `.lobsiteignore` itself are always left out.

Secret files (`.env*`, private keys such as `*.pem` and `id_rsa`, `.npmrc`, `.netrc` and similar) stop a deploy until they're removed or ignored. In a terminal, the CLI offers to add them to `.lobsiteignore` and deploy without them.

## Forms

```html
<form action="/_lobsite/forms/contact" method="POST">
  <input name="email" type="email" required>
  <textarea name="message" required></textarea>
  <button>Send</button>
</form>
```

Forms are found at deploy time. Spam protection (a honeypot, timing and rate limits) is added for you. Submissions land on your dashboard's Submissions page and in your email. [More on forms](https://lobsite.com/docs/forms): examples, sending with JavaScript, frameworks and settings.

On the free plan, forms run in limited mode: a monthly quota per site, notifications to your account email only, and no webhooks. The Standard plan adds webhooks, any verified notification address and a higher quota.

## Custom domains

Custom domains come with every account, the free plan included. `lobsite domain add www.example.com` prints the record to add: a CNAME to `cname.lobsite.app`. Certificates are issued and renewed for you. If another account has also added the domain, a TXT record proves it's yours.

## Previews and rollback

Every deploy has its own URL, `<id>--<site>.lobsite.app`. `lobsite deploy --preview` leaves production alone; `lobsite rollback` and `lobsite promote` switch the live deploy without uploading.

## CLI

| Command | What it does |
| --- | --- |
| `lobsite [dir]` | Deploy a folder (the default command) |
| `lobsite deploy --preview` | Upload without changing production |
| `lobsite deploys` | List kept deploys |
| `lobsite rollback [id]` | Make an earlier deploy live |
| `lobsite promote <id>` | Make any deploy live |
| `lobsite login / logout / whoami` | Your account |
| `lobsite claim [site]` | Keep an anonymous site |
| `lobsite account [use <email>\|me]` | Switch to an account you're a member of |
| `lobsite token create\|ls\|revoke` | CI tokens for LOBSITE_TOKEN (Standard) |
| `lobsite ls / open / rm` | Your sites |
| `lobsite domain add\|status\|rm` | Custom domains |
| `lobsite forms ls / export <name> --csv` | Form submissions |
| `lobsite mcp` | An MCP server for AI agents |

## Limits

|  | Anonymous | Free | Standard |
| --- | --- | --- | --- |
| Sites | No cap | 1 | 5 |
| Files per site | 100 | 100 | 10,000 |
| Per file | 5 MB | 5 MB | 100 MB |
| Site size | 50 MB | 50 MB | 2 GB |
| Storage | — | 1 GB | 20 GB |
| Deploys an hour | 10 | 30 | 100 |
| Deploys a day per site | 3 | No cap | No cap |
| Deploy history | Live deploy only | 7 days | 30 days |
| Custom domains per account | — | 1 | 5 |
| Custom domains per site | — | 1 | 1 |
| Bandwidth | 1 GB | 10 GB | Unlimited, fair use |
| Form submissions a month | — | 25 | Unlimited |
| Analytics | — | — | Yes |
| Automations (Zapier, n8n) | — | — | Yes |
| "Powered by lobsite!" badge | Yes | Yes | No |

Bandwidth is per month per account (per site lifetime for anonymous sites). At the limit, free and anonymous sites stop serving until the next month; on Standard there's no cap and sites keep serving: past 1 TB a month, we contact you.