# Shareabl

> Shareabl hosts apps at https://{slug}.shareabl.app, and anyone can remix a public app into
> their own running copy. These docs are everything an AI agent needs to publish and change
> apps on Shareabl.

This page is the overview. Each feature has its own page (listed below): **read a feature's
page before you use it.** It says what works, what doesn't yet, and the limits. Every page is
plain Markdown at `https://shareabl.app/docs/{topic}.md`, and all of them are in one file at
https://shareabl.app/llms-full.txt. Once connected, `read_docs({ topic })` returns the same
pages (in a terminal: `npx shareabl read_docs --topic payments`).

## Connect

The person needs a Shareabl account, which is free: signing in with their email makes one
(https://shareabl.app/signin, or the sign-in prompt below).

- **Chat apps (ChatGPT, Claude, other MCP clients):** add the MCP server
  `https://shareabl.app/mcp`. You'll be asked to sign in to Shareabl and allow access.
- **Agents with a terminal (Claude Code, Codex, ChatGPT Work, Cursor):** run
  `npx shareabl login`, give the person its link to allow, then run it again.

## Start here

- `start_here()`: who you're signed in as, your apps (and their drafts), and what to do
  next. Call it at the start of a conversation, or whenever you've lost track.
- A plain page is just `index.html`: `publish({ slug: "my-page", write: [{ path: "index.html",
  content: "<!doctype html>…" }] })` makes it live at `https://my-page.shareabl.app`.
- To change an app: `list_files` or `search_files`, `read_file` (note each file's `hash`), then `edit_file`
  for changes within a file or `publish` for new files and rewrites, passing `expectHash`
  so you never overwrite someone else's change.
- Not sure? `preview: true` puts a change in the app's draft, with a link to check first.
- Undo: `list_versions`, then `activate_version`.
- Errors come back as `code: message` naming the wrong fields; fix them and retry.

## What Shareabl does, and what your app does

Shareabl does what an app can't be trusted to do itself (take payments, sign people in,
deliver messages, call AI models on the owner's key) and tells the app what happened. Your
app owns everything else: its tables, its pages and its flow. The pages below say what each
feature guarantees; how you use them is your design to decide. Read the first page before
designing an app.

## Pages

- [What Shareabl does, and what your app does](https://shareabl.app/docs/boundary.md): Your tables and flow are yours; payments, sign-in, messages and AI are Shareabl's.
- [Apps: files, publishing and versions](https://shareabl.app/docs/apps.md): What an app is, publishing and editing, drafts, versions, comments, the CLI and HTTP.
- [Vars: what the next owner changes](https://shareabl.app/docs/vars.md): Values an owner sets without code, and what resets on remix.
- [Data: tables, rules and live updates](https://shareabl.app/docs/data.md): Each app's own SQLite database, migrations, seed rows, who may read and write.
- [Sign-in and private pages](https://shareabl.app/docs/sign-in.md): Visitors signing in to an app, who they are in code, owner-only pages, an app only you can use.
- [Server code, keys and schedules](https://shareabl.app/docs/server.md): server/index.js, outside APIs and their keys, schedules, publishing live updates.
- [Agents, tools and ways in](https://shareabl.app/docs/agents.md): Chat and tools other AIs use, agents that work on their own (env.AI.run), and trying each way in.
- [Messages and notifications](https://shareabl.app/docs/messages.md): Telling the owner or a visitor something, an email list people subscribe to, and emails for new rows.
- [Payments](https://shareabl.app/docs/payments.md): Products, checkout, cards or paying later, and orders.
- [AI](https://shareabl.app/docs/ai.md): Calling models on the owner's key: text, speech read aloud with each word's time, pictures, and web search.
- [Visitors and stats](https://shareabl.app/docs/stats.md): How many people visit an app, from where, how it's used, and counting your own events (shareabl.track).
- [Remix](https://shareabl.app/docs/remix.md): What a copy gets, and what to check when you work on one.
- [Limits and errors](https://shareabl.app/docs/limits.md): Every limit an app runs into, and the error codes.
- [Tools: making and publishing](https://shareabl.app/docs/tools.md): Each tool for files, versions, checks and publishing, and what it takes.
- [Tools: running and trying an app](https://shareabl.app/docs/tools-run.md): Each tool for trying ways in, data, settings, logs and money, and what it takes.

## Coming soon

Visitor file uploads. Don't use them yet.