# altstack.json reference

Every AppKeep app has an `altstack.json` next to its `package.json`. `npx appkeep check` validates it. The build guide
(/docs/build-an-app.md) explains how each part is used.

## Identity and listing

| Field | Required | What it is |
|---|---|---|
| `schema` | yes | Always `1` |
| `slug` | yes | The app's address: `<slug>.appkeep.app`. Lowercase letters, digits and dashes. Can't change after the first publish |
| `name` | yes | Shown on the store and in the app's tab |
| `version` | yes | Semver. Bump it every time you publish |
| `tagline` | | One line under the name on the listing |
| `description` | | The listing's longer text (plain text, blank lines start paragraphs) |
| `category` | | One of `marketing`, `analytics`, `creative`, `sales`, `forms`, `scheduling`, `support`, `productivity`, `finance`, `other` |
| `price_cents` | | One-time price in US cents. `0` (or leaving it out) makes the app free. Buyers still need a hosting plan |
| `replaces` | | `[{ "name": "DocuSign", "monthly_cents": 2500 }]`: products this is an alternative to and their usual monthly price per seat. Buyers find apps by these names |
| `icon` | | A square SVG (under 32 KB), e.g. `"icon.svg"` |
| `license`, `original_source` | | For ports of open-source apps: the license and the original repository |

## Store page

| Field | What it is |
|---|---|
| `screenshots` | **At least 1**, up to 10: `[{ "src": "store/home.png", "caption": "…" }]`. PNG, JPEG, WebP or GIF up to 5 MB, or MP4/WebM video up to 25 MB with a `"poster"` image. Captions up to 120 characters |
| `features` | Up to 8: `[{ "title": "…", "body": "…", "media": "store/x.png", "poster": "…" }]`. Title up to 60 characters, body up to 400 |

Paths are relative to altstack.json. `publish` uploads these files (CLI 0.3.0 or later) and leaves them out of the app and its source.

## Code

| Field | What it is |
|---|---|
| `entry` | The Worker's entry file, e.g. `"src/index.ts"`, bundled by the CLI |
| `build` | For apps built by their own toolchain: `{ "command": "npm run build", "prebuilt": "dist/worker.js", "assets": "public" }`. `command` runs before check, pack, publish and push (`--no-build` skips it); `prebuilt` is the ES module to run instead of bundling `entry`; `assets` is a folder of static files served at their paths before the Worker runs |
| `migrations` | Folder of `.sql` files run in name order, once each (default `"migrations"`) |
| `healthcheck` | Path the review requests as a visitor and as the owner (default `"/"`). It must not answer 5xx |
| `compatibility_date` | Workers compatibility date |
| `exclude` | Folders or files left out of the package and the source, e.g. `["apps/ios", "docs"]` |
| `include_source`, `allow_changes` | Must both be `true`: every app is customizable |

## Permissions (shown to buyers, each with its `why`)

| Field | What it is |
|---|---|
| `egress` | Hosts the app may `fetch()`: `[{ "host": "api.example.com", "why": "…" }]`. Anything else gets a 403 |
| `services` | Platform services: `email`, `members`, `storage`, `ai`, `wallet`, each `{ "name": "email", "why": "…" }` |
| `connections` | Third-party accounts the buyer connects (Google, Slack, …): `{ "provider": "google", "scopes": [...], "why": "…" }`. See /llms.txt for the providers |
| `ratelimits` | `[{ "name": "SIGN_LIMIT", "limit": 30, "period": 60 }]` (period 10 or 60 seconds) becomes `env.SIGN_LIMIT.limit({ key })` |
| `settings` | Values the buyer fills in: `{ "key": "ORG_NAME", "label": "…", "help": "…", "default": "…", "required": false, "secret": false }`, read as `env.ORG_NAME`. `"generate": "secret"` fills in a random secret per copy that buyers never see |
| `tools` | AI tools served at `POST /_altstack/tools/<name>`: `{ "name", "description", "risk": "read" \| "write" \| "destructive", "input": { JSON Schema } }` |
| `cron` | `["* * * * *"]` or `["*/N * * * *"]`: runs the Worker's `scheduled()` handler |
