# heremyapp docs

heremyapp publishes static websites and app installers (.pkg, .dmg, .zip) built by AI coding agents.
Your agent uses a small HTTP API (a site deploy is one request) and gets a permanent public URL. No hosting, DNS or SSL setup.

## Concepts

| Term | Meaning |
|---|---|
| Account | Your username, for example `peter`. It is part of every URL. |
| Space | One website, for example `mac-utility`. Its public URL never changes. |
| Deployment | One upload of a site's files. The published one is live; older ones can be restored. |
| Artifact | One version of an installer file, with permanent download URLs. |
| Token | A bearer token (`hma_...`) that authorizes API calls. |

## URLs

| What | URL | Notes |
|---|---|---|
| Public site | `https://heremyapp.com/ACCOUNT/SPACE` | Share this one. It redirects to the site's own isolated origin, which may change. |
| Latest installer | `https://heremyapp.com/dl/ACCOUNT/SPACE/latest/FILENAME` | Always the most recently published version |
| Fixed installer version | `https://heremyapp.com/dl/ACCOUNT/SPACE/v/VERSION/FILENAME` | Never changes |
| API | `https://api.heremyapp.com/v1` | JSON in and out |

## Quickstart

Set up the shell once (see [Authentication](https://heremyapp.com/docs/authentication.md)):

```bash
export HEREMYAPP_TOKEN="${HEREMYAPP_TOKEN:-$(cat ~/.config/heremyapp/token 2>/dev/null)}"
API=https://api.heremyapp.com/v1
AUTH="Authorization: Bearer $HEREMYAPP_TOKEN"
```

Create a space, deploy a folder that contains `index.html`, and open the public URL:

```bash
curl -sS -X POST "$API/spaces" -H "$AUTH" -H "content-type: application/json" \
  -d '{"slug":"my-app","name":"My App"}' -w '\nHTTP %{http_code}\n'    # 201 created, 409 already exists

tar -czf - -C dist . | curl -sS --fail-with-body -X POST "$API/spaces/my-app/deployments" \
  -H "$AUTH" -H "content-type: application/gzip" --data-binary @-
```

The deploy response contains `public_url`, for example `https://heremyapp.com/peter/my-app`.

## Pages

- [Authentication](https://heremyapp.com/docs/authentication.md): tokens, scopes, where agents find the token
- [Static sites](https://heremyapp.com/docs/sites.md): deploying, file rules, URL resolution, rollback
- [Installers](https://heremyapp.com/docs/installers.md): publishing .pkg, .dmg and .zip files with permanent download links
- [Releases and versioning](https://heremyapp.com/docs/releases.md): build numbers and semantic versions, managed by the agent on every deploy
- [Landing page checklist](https://heremyapp.com/docs/landing.md): contact details, what to include, what people forget, multiple languages
- [Privacy policy and terms](https://heremyapp.com/docs/legal.md): when you need them, templates, `/privacy` and `/terms`, app store fields
- [For AI agents](https://heremyapp.com/docs/agents.md): what to tell your agent, the recommended workflow, the agent skill
- [API reference](https://heremyapp.com/docs/api.md): every endpoint, error code and limit

Every page is also plain Markdown: add `.md` to its URL (for example `https://heremyapp.com/docs/sites.md`).
All pages in one file: `https://heremyapp.com/llms-full.txt`.

## Conventions

- UPPERCASE words such as `ACCOUNT`, `SPACE` and `ARTIFACT_ID` are values taken from earlier responses.
- Commands use the `API` and `AUTH` shell variables from the quickstart.
- `curl -sS --fail-with-body` prints the error body and exits non-zero on an HTTP error (curl 7.76 or newer).
- Responses are JSON. Read the fields directly, or use `jq -r .id` if `jq` is installed.