Apps

Deploying an app

This page walks through the full deploy workflow for a Runtype App: create the app, upload a version, and activate it. If you are new to apps, start with What are Apps?.

Runtype Apps is in early access. You can deploy through the REST API, the Runtype CLI (runtype apps), the MCP tools, or the dashboard Apps page. The serving edge ships separately, so a freshly deployed app may not serve traffic yet in every environment.

Before you start

You need:

  • An API key with the APPS:WRITE permission (or *). See Managing API keys.
  • A built static app: a folder with index.html at the top level.
  • A runtype.app.json manifest next to your index.html. A minimal manifest is just a name:
1{
2  "name": "My App"
3}

If your app calls flows or agents, list their ids under capabilities. The full manifest reference is in Deploying Runtype Apps.

Step 1: Create the app

Pick a slug (lowercase letters, digits, and hyphens; it must start with a letter):

$curl -X POST https://api.runtype.com/v1/apps \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "slug": "retro-board", "name": "Retro Board", "visibility": "unlisted" }'

The response includes the app’s id and its permanent URL:

1{
2  "id": "app_01h2x...",
3  "slug": "retro-board",
4  "hostname": "retro-board-x7k2p9",
5  "url": "https://retro-board-x7k2p9.runtype.run",
6  "activeVersionId": null,
7  "visibility": "unlisted",
8  "status": "active"
9}

Creating the app also auto-provisions a client token scoped to that URL. Nothing serves yet: activeVersionId is null until your first activation.

Step 2: Zip and upload a version

Zip your built output. Both of these layouts work, because a single wrapper directory (like dist/) is stripped automatically:

$# Zip the contents of dist/
$cd dist && zip -r ../bundle.zip . && cd ..
$
$# Or zip the dist/ folder itself
$zip -r bundle.zip dist/

Upload the zip as the raw request body:

$curl -X POST https://api.runtype.com/v1/apps/APP_ID/versions \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/zip" \
>  --data-binary @bundle.zip

The response is a new version with "status": "uploaded" and a versionNumber. Uploading never changes what is served.

Common upload errors:

  • 400 if the zip is missing index.html or runtype.app.json at the root, exceeds your plan’s size limit or the 500-file cap, or references flows or agents you do not own
  • 402 if apps are not enabled on your plan
  • 422 if the manifest sets auth to anything other than "none"

Step 3: Activate the version

$curl -X POST https://api.runtype.com/v1/apps/APP_ID/activate \
>  -H "Authorization: Bearer YOUR_API_KEY" \
>  -H "Content-Type: application/json" \
>  -d '{ "versionId": "apv_01h2x..." }'

Activation flips the active-version pointer, syncs the app’s client token to the manifest’s flows and agents, and updates edge routing. The response contains both the updated app and the now-active version.

Using the CLI

The Runtype CLI wraps the same workflow in two commands:

$# Create the app
$runtype apps create --slug retro-board --name "Retro Board"
$
$# Zip, upload, and activate a built bundle in one command
$runtype apps deploy ./dist --app APP_ID

runtype apps deploy zips the directory (it must contain index.html and runtype.app.json at its root), uploads it as a new version, and activates it. Pass --no-activate to stage the version without changing what is served.

Rolling back from the CLI is two commands: list the history, then activate an older version.

$runtype apps versions APP_ID
$runtype apps activate APP_ID VERSION_ID

runtype apps list and runtype apps delete APP_ID round out the management commands.

Rolling back

A rollback is just activating an older version. List the version history, then activate the one you want:

$curl https://api.runtype.com/v1/apps/APP_ID/versions \
>  -H "Authorization: Bearer YOUR_API_KEY"

Versions are returned newest first. Pass any previous version’s id to the activate endpoint and the app instantly serves that version again.

Managing the app

  • Rename, change visibility, or suspend: PATCH /v1/apps/APP_ID with any of name, description, visibility, or status. Setting "status": "suspended" makes the app’s URL return 410 Gone until you set it back to "active".
  • Delete: DELETE /v1/apps/APP_ID removes the app, its versions, and its routing, and deactivates the auto-provisioned client token. Stored files are cleaned up in the background.

Making an app public requires a paid plan; the request returns 402 otherwise.

Next steps