Your first app deployment

VelaOS deploys apps in rings: canary → pilot → broad → global. Each ring has a soak period (default 24h) where failures auto-pause the rollout if the error rate exceeds 5%. This is how you ship apps to 10,000 devices without a 3 AM page.

1. 1

   Upload the APK

   Go to Catalog → Upload. Drag your APK onto the drop zone.

   The console reads the package name, version, versionCode, signing cert, and minSdk automatically. You can rename the display name, add icons, and set the short description.

   The APK file is stored in Supabase Storage (bucket app-packages) with a 1-hour presigned URL on deployment. You never distribute the raw file — the agent downloads via an authenticated URL.
2. 2

   Create a deployment to canary

   Click the app, then Deploy → New release. Choose:

   • Ring: Canary
   • Target: a group (e.g. "Canary devices") or specific device IDs
   • Soak period: 24 hours (default)
   • Failure threshold: 5% (default)

   Click Deploy. The console fires app_install commands to every device in the target. Each device reports back installed or failed.

3. 3

   Watch the canary ring

   The release page shows a live progress bar:

   Canary ring — 12/15 devices
     ✅ 12 installed
     ⏳  2 pending
     ❌  1 failed  (0x7F4B2C — INSTALL_FAILED_INSUFFICIENT_STORAGE)
   
   Soak: 6h remaining
   Failure rate: 6.7% (exceeds 5% threshold)
   ⚠️  Rollout auto-paused

   If this happens, click the failed device to see the agent log. Fix storage, redeploy to that device only, then click Resume rollout.

4. 4

   Promote to pilot

   Once canary soak completes with failure rate ≤ threshold, the Promote to Pilot button enables. Click it.

   The pilot ring typically targets a larger group — 10–20% of your fleet. Same soak period, same threshold.

5. 5

   Promote to broad, then global

   Broad is usually 50–80% of the fleet. Global is everyone else. Each ring uses the same soak + auto-pause logic.

   At any point you can:

   • Pause — stop any new devices from receiving the update
   • Rollback — push the previous version to all devices on this ring
   • Hold ring — complete this ring but don't promote to the next automatically
6. 6

   Verify on a device

   Open the device detail page → Apps tab. Your app appears with:

   • Package name, version, versionCode
   • Install timestamp and source (which release)
   • Launch / force-stop / clear-data buttons

   Use Live View to see the app actually running.

Via the API

Everything above is also available as REST endpoints. To deploy an uploaded app via curl:

curl -X POST https://api.velaos.ch/api/v1/apps/abc123/deploy \
  -H "X-API-Key: vela_live_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "group_id": "canary-group-uuid",
    "ring": "canary",
    "soak_hours": 24,
    "failure_threshold_pct": 5
  }'

See API Reference: Apps for all deployment endpoints.

Next steps

• Ring deployment in depth — picking ring sizes, soak periods, thresholds
• Catalog reference — every button on the catalog page
• OTA model — how ring deployment differs from OS updates