# AI agents

Coding agents (Claude Code, Cursor, Codex and others) deploy with the same CLI as people, and chat assistants without a filesystem deploy through a remote MCP server. This page shows how to set each one up.

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

## How agent mode works

The CLI knows it runs under an agent from the variables agents set: `CLAUDECODE` (Claude Code), `CURSOR_AGENT` (Cursor), `CODEX_SANDBOX` (Codex), `GEMINI_CLI`, `COPILOT_AGENT`, `GOOSE_TERMINAL`, `REPLIT_AGENT` and `AGENT`. Set `LOBSITE_AGENT=<name>` to name another agent, or `LOBSITE_AGENT=0` to turn agent mode off. Under an agent:

- Nothing is ever asked. The first deploy of a folder prints its summary and carries on; commands that can't be undone need `--yes`.
- There are no colours, spinners, QR codes or clipboard copies, only plain lines.
- A deploy ends with a line written for the agent to pass on:

```text
Tell the user: the site is live at https://quiet-fox-4821.lobsite.app. It's temporary and is removed in 6h. To keep it, open https://lobsite.com/claim/quiet-fox-4821#lob_claim_… and sign in (free).
```

Sites deployed without an account last 6 hours. The claim link keeps the site: the person opens it and signs in, without touching a terminal. Running the same command again updates the same site, because `lobsite.toml` remembers it.

## Claude Code

Claude Code can deploy with the shell command alone. To have it use Lobsite every time, add a line to the project's CLAUDE.md:

```text
Deploy with `npx -y lobsite --yes` and relay the "Tell the user:" line from the output.
```

Or add the MCP server, which gives Claude tools to deploy, list sites and deploys, roll back and promote:

```sh
claude mcp add lobsite -- npx -y lobsite@latest mcp
```

## Cursor

Add the MCP server to `.cursor/mcp.json`:

```json
{ "mcpServers": { "lobsite": { "command": "npx", "args": ["-y", "lobsite@latest", "mcp"] } } }
```

Or add a project rule in `.cursor/rules/` with the section from [AGENTS.md](#agents-md).

## Codex and other agents

Codex and the other agents that read AGENTS.md pick up a section like this one. Paste it into the project's AGENTS.md:

````md
## Deploying

This site deploys with [Lobsite](https://lobsite.com). Build it, then from the project folder run:

```bash
npx -y lobsite --yes
```

- Tell the user the URL, and relay the "Tell the user:" line from the output word for word.
- Sites deployed without logging in are removed after 6 hours. The claim link in the output keeps the site; the user opens it and signs in.
- `lobsite.toml` remembers the site, so the same command updates it. Use `--preview` to deploy without changing the live site, and `--json` for machine-readable output.
- If a deploy fails, follow the fix in the error message. Never pass `--include-secrets`.
````

Any agent that speaks MCP over stdin/stdout can run `npx -y lobsite@latest mcp` instead.

## ChatGPT and Claude.ai

Chat assistants write pages but have no folder to deploy. Add Lobsite as a custom connector (an MCP server) with this URL:

```text
https://lobsite.com/api/mcp
```

It speaks Streamable HTTP and has one tool, `deploy_files`, which takes the files' contents. Then ask the assistant to put the page online. Sites deployed this way have no account: the answer carries the claim link that keeps them.

## Without Node: curl

Where `npx` can't run, one curl command deploys a page or a few files and answers with the URL, the claim link and how to update the site:

```sh
curl --data-binary @index.html https://lobsite.com/api/v1/drop
curl -F index.html=@index.html -F css/site.css=@site.css https://lobsite.com/api/v1/drop
```

To update the same temporary site, pass its name and the claim token from the first answer:

```sh
curl --data-binary @index.html -H "Authorization: Bearer lob_claim_…" "https://lobsite.com/api/v1/drop?site=quiet-fox-4821"
```

`?preview=1` deploys without changing the live site. A direct deploy carries up to 25 MB. Add `?format=json` for a JSON answer.

## MCP tools

| Server | Tools |
| --- | --- |
| Local: `npx -y lobsite@latest mcp` | `deploy`, `list_sites`, `list_deploys`, `rollback`, `promote`, `whoami` |
| Remote: `https://lobsite.com/api/mcp` | `deploy_files` |

The local tools run the CLI commands with `--json --yes` and take `path`, the project folder (by default, the folder the server started in). `deploy` answers with the "Tell the user" line first. Logging in and deleting sites aren't tools: one needs the person in a browser, the other can't be undone.

## JSON output

`--json` prints one JSON object on stdout, with logs on stderr:

```json
{
  "site": "quiet-fox-4821",
  "deploy_id": "d7k2m9qa",
  "url": "https://quiet-fox-4821.lobsite.app",
  "preview_url": "https://d7k2m9qa--quiet-fox-4821.lobsite.app",
  "live": true,
  "expires_at": "2026-10-13T16:20:38Z",
  "claim_url": "https://lobsite.com/claim/quiet-fox-4821#lob_claim_…",
  "files": { "total": 42, "uploaded": 3 },
  "bytes_uploaded": 14336,
  "duration_ms": 812
}
```

`claim_url` and `expires_at` are `null` for sites with an account. A failure is `{ "error": { "code", "message", "why", "fix", "exit_code", "retryable" } }`. Branch on `code`, which never changes (see [Errors](https://lobsite.com/docs/errors)), and retry only when `retryable` is true.