Apps & Deployment

The platform's core story: create an app from a template, push code to the built-in Git remote, request a deploy, and it's live at {app}.{org}.kapable.run. The full lifecycle — environments, env vars, deployment lanes, logs, pause/resume — is part of the auth SDK module today (the methods live on client.auth).

The deploy flow

1. Create an app from a template with createAppChoice (use the elysia starter — see the template note below).
2. Authenticate & push your code to the app's Forgejo remote (see "Pushing your code" below).
3. Deploy with requestDeploy. The CI pipeline builds and starts the app.
4. Your app is live at https://{app}.{org}.kapable.run.

Pushing your code

The app's repo lives at git.kapable.dev. Mint a scoped bot token for it, then push over HTTPS with the bot username embedded in the URL:

# 1. Mint a per-app Forgejo PAT (token shown once)
curl -X POST -H "Authorization: Bearer kses_..." \
  https://api.kapable.ai/v1/apps/{app_id}/bot-pat
# → { "token": "...", "bot_username": "kbot-{app}" }   (bot_username is also on the app detail)

# 2. Push using bot_username:token@ (repo_url is returned when the app is created)
git remote add kapable https://kbot-myapp:PAT@git.kapable.dev/{org}/{repo}.git
git push kapable main

Watching a deploy

requestDeploy returns 202 {"status":"requested"}. Poll GET /v1/apps/{app_id} (getAppDetail) to watch progress:

• current_step / step_index / total_steps — live build progress.
• deployment.status passes through requested → building → live_pending_tls. On failure, build_log_tail + failed_step tell you why.
• Heads-up: the app's top-level status can stay created even while the deployment is serving. Confirm liveness by requesting the public_url directly (it returns 200 over TLS once live).

Apps & templates

SDK Examples

// 1. Create an app from the elysia starter template
const choice = await client.auth.createAppChoice({
  user_id: me.user.id,
  org_id: me.org.id,
  org_slug: 'acme',
  template_slug: 'elysia',
  app_name: 'my-api',
});

// 2. Push code to the app's Forgejo remote, then:

// 3. Request the first deploy
await client.auth.requestDeploy(choice.id);

// 4. Live at https://my-api.acme.kapable.run

// Same flow in Rust (methods on client.auth())
let choice = client.auth().create_app_choice(&CreateAppChoiceRequest {
    user_id: me.user.id,
    org_id: me.org.id,
    org_slug: "acme".into(),
    template_slug: "elysia".into(),
    app_name: "my-api".into(),
}).await?;

client.auth().request_deploy(choice.id).await?;

Deployments & runtime control

Environments & env vars

Apps have named environments (e.g. production), each with its own env-var set and deployment lanes. A simpler app-level env API (listAppEnv / upsertAppEnv / deleteAppEnv) also exists at /v1/apps/{app_id}/env.

Deployment lanes

Lanes are parallel deployment tracks within an environment (blue/green, canary). Promote a lane to make it the live one; drain it to stop routing traffic.

SDK Examples

// Set an env var on production, then deploy to a canary lane
await client.auth.createAppEnvVar(appId, 'production', {
  name: 'FEATURE_FLAG_X',
  value: 'on',
});

await client.auth.deployToLane(appId, 'production', 'canary');

// Happy with the canary? Promote it.
await client.auth.promoteLane(appId, 'production', 'canary');

// Tail recent logs
const logs = await client.auth.appLogs(appId, { lines: 200 });

client.auth().upsert_app_env(app_id, "FEATURE_FLAG_X",
    &EnvVarUpsertRequest { value: "on".into() }).await?;
client.auth().promote_lane(app_id, "production", "canary").await?;
let logs = client.auth().app_logs(app_id, Some(200)).await?;

Health checks

Every app should serve GET /health returning any 2xx — fast and dependency-free (no DB calls). The platform's lane prober uses it for granular health detection, and the deploy pipeline health-gates new containers on it.

• 2xx — healthy; the lane routes traffic.
• 404 — treated as alive but unmonitored: your app keeps serving, it just loses granular health detection. You will never be taken down for lacking the route.
• Other non-2xx — the app is considered alive but unhealthy; the router routes away from the lane until it recovers.

Public /health on {app}.{org}.kapable.run proxies straight through to your app like any other path. New scaffolds and the seed templates ship the route by default. For React Router, it's a resource route:

// app/routes/health.ts
export function loader() {
  return new Response(JSON.stringify({ status: "ok" }), {
    status: 200,
    headers: { "Content-Type": "application/json" },
  });
}

// app/routes.ts
import { type RouteConfig, index, route } from "@react-router/dev/routes";
export default [
  route("health", "routes/health.ts"),
  index("routes/home.tsx"),
] satisfies RouteConfig;

Static sites (the blank stack) can commit a plain file named health at the repo root — it's served at /health with a 200. Other stacks: any one-line GET /health handler works.