Managing App Builds & Versions

The Apps page is where you manage the applications you want to test on VibeView’s cloud simulators and devices. You can upload iOS, Android, Apple TV, Android TV and Roku apps, organize builds by version, and open each app’s tests.

Apps list

The Apps page lists every application in your organization as a table. Each row shows:

• Name — the app name and its package identifier. A Live marker appears next to the name while a session is running against that app.
• Platform — iOS, Apple TV, Android, Android TV, or Roku.
• Latest build — the newest build’s version and build number.
• Builds — how many builds the app has.
• Last played — when a session last ran against the app, or Never.

Hovering a row reveals a Play button, which opens Devices with the app selected, and a menu holding Delete. If a session of yours is already running that app, Devices says so above the stage, with Open it to go back to it; your running sessions are also listed in the Running section of the device list. The same goes for Start session on the app’s page and the play button next to a build.

Search the list with the box in the page header; pressing / anywhere on the page puts the cursor in it. The tabs under the header filter by platform and show how many apps each one has; only platforms you actually have appear.

Apps on several platforms

When the same app is linked across platforms (see Same app on other platforms), the list shows it as one row: its name, a chip for each platform, each platform’s latest build, the builds of all of them together, and when any of them was last played. Click the arrow next to the name to show one row per platform, each with its own Play button and Delete menu. Click the row itself to open the app’s page on All. Searching for the app’s name finds the row; picking a platform tab shows just that platform’s app as an ordinary row.

Once at least one app is linked, Per platform next to the platform tabs switches back to one row per app on every platform, and By app groups them again. Your choice is remembered in this browser.

When VibeView finds apps that look like the same app on several platforms but aren’t linked yet, Developers and Admins see a line above the table, for example “3 apps are on several platforms but aren’t linked yet.” Review and link lists each suggestion with why it was suggested (the same bundle ID or package name, or the same name); nothing is linked until you click its Link. A link that isn’t allowed shows the reason in the same list. Not now hides the line until a new suggestion appears; it also hides those suggestions on the Tests page.

Sample apps

Every new organization starts with a few VibeView sample apps so you can open a session before you have a build of your own: Atlas (iOS and Android), TV Catalog (Apple TV), and JetStream (Android TV). They are labelled Sample on the Apps page and on the app’s own page, and otherwise behave exactly like apps you upload — play them on a live device, record and run tests against them, share or embed them, and delete them when you no longer need them. The label goes away once you upload a build of your own to that app.

Uploading an app

To upload a new app, click Upload app on the Apps page. The same upload dialog is used everywhere you add a build in VibeView (the Apps list and the app detail page’s Upload build), so the flow is identical across entry points. It has two tabs: Upload a file, for a build you already have, and Let your agent do it (see below). Under both tabs, a link to Preparing your build explains what each platform needs.

If the file is identical to a build the app already has, nothing new is added: the message says which build it already is and when it was uploaded, with a link to the app.

VibeView supports the following formats:

• iOS and tvOS: .app simulator bundles, compressed as .zip, .tar.gz, or .tgz
• Android and Android TV: .apk packages
• Roku: the channel’s sideload .zip, with manifest, source/ and components/ at the root of the archive

Not sure how to produce one of these files? See Preparing Your App Build for per-platform and per-framework instructions.

Uploads are limited to 500 MB per file. Files are validated on the server using magic byte checks to confirm the file matches the declared format, so renaming a file extension will not bypass validation.

After selecting a file, the modal also shows a Note (optional) textarea before you submit. See Build notes below.

After uploading, the app appears in the list and the first build is created automatically.

Let your coding agent build and upload it

If you work with a coding agent (Claude Code, Codex, Cursor or another), it can produce the simulator build and upload it for you. Open the upload dialog and choose Let your agent do it:

• Coding agent: pick your agent and click its Copy prompt button (for example Copy prompt for Claude Code), then paste it into the agent in your app’s repository. The prompt tells the agent which build format VibeView needs, how to sign in (npx vibeview login, which opens your browser; the prompt never contains a token), and to upload with npx vibeview upload-app. View prompt shows the full text first.
• Terminal: the same steps as commands to run yourself.

The dialog watches for the new build. When it arrives, the dialog closes and the usual upload message appears (on the Apps page, or when the build lands in a different app, it links to the app with Open app), so you don’t need to refresh the page. If the agent’s build turns out to be a different app (for example, it has another bundle identifier), the message names that app instead. Warnings about a build that can’t run on some devices appear in the agent’s output and on the build’s Runs on badge.

While your organization has no apps of its own, the Apps page shows Developers and Admins Add your first app (or Add your own app above the sample apps) with three ways in: Ask your agent, Terminal and Dashboard. Once you have an app of your own, a one-line Ask your agent to build and upload a new version hint sits under the table instead. Get the prompt in either opens the upload dialog on Let your agent do it.

App detail page

Click any app in the list to open its detail page. From here you can:

• See every build for the app
• Upload another build
• Open the app’s tests on the Tests page (see The Tests page)

The panel at the top of the page carries the app icon, its name (with a Live now marker when a session is running), the package identifier, the platform, and a readout of the latest version, latest build, latest upload, total builds, and sessions in the last 7 days. Upload build, Tests, Explore this app (Developers and Admins: an Explore run on this app), Start session and a menu holding Delete app sit in the bar above it. If a cloud build failed in the last day, a Needs attention line appears above the build history with the failure and a link to the full build history.

For an app that is linked across platforms, a row of buttons above the panel switches platform: All and one button per platform, for example iOS, Android, Apple TV, Android TV or Roku. The app’s own platform is selected when you open it. Picking a platform opens that platform’s app page, so each platform keeps its own address you can bookmark or share.

All shows the linked apps together:

• the panel shows the number of platforms, the builds of all of them, the latest upload and the sessions in the last 7 days;
• Build history lists every platform’s builds in one table, newest first, with a Platform column, and every row’s actions act on that platform’s app;
• Share lists the share links and embeds of every linked app;
• Build settings asks you to pick a platform, because signing and variables belong to one app.

On All, Start session, Upload build, Explore this app and Delete app first ask which platform you mean, and Share this app on the Share tab waits for you to pick one. Upload build, Explore this app and Delete app are shown to Developers and Admins only.

Build history

Each app can have multiple builds. The Build history table lists them sorted by upload date, with the most recent build shown first. Every build displays the following metadata:

• Build — the app’s version string (e.g., 1.2.0). React Native and Expo builds get a tag for their build configuration: debug for a debug build (one that can connect to a Metro dev server) and release for a release build, on iOS, Android, Apple TV and Android TV alike. A debug build that doesn’t embed its JavaScript bundle also gets a needs Metro tag: it only runs with a Metro dev server attached, so open it with vibeview dev. A debug build that embeds its bundle runs on its own and has no needs Metro tag. Builds of apps that aren’t React Native (native or Flutter apps) get no tag — they never need Metro, so VibeView treats them like release builds when it picks which build to install.
• Architectures (Android builds) — the native architectures the build ships, listed in the build’s details. Which devices can run them is shown by the Runs on badge. See Preparing Your App Build: Architecture.
• Runs on — a badge showing whether VibeView devices can run the build: Runnable; when only some devices can run it, the most specific reason: iPad only, Some devices (native code), a minimum OS such as iOS 17.0+, or Some devices; No compatible device when no VibeView device can run it today (it starts working once one can); or Can’t run: … with the reason (for example split APK or device build). Click the badge to see what’s wrong and how to fix it. A build that can’t run is kept in the history, but VibeView never starts a session with it.
• Build # — the internal build identifier
• Size — size of the uploaded file
• Tags — any tags attached to the build
• Note — the optional note entered at upload time (see below)
• Uploaded — when the build was added
• Uploaded by — who added the build
• Source — shows a CI badge for builds uploaded from a CI pipeline

To add a new build, click Upload build in the bar at the top of the app detail page. The same format and size restrictions apply as when uploading a new app. The build must be the same app: a file whose package name (Android) or bundle identifier (iOS) differs from the app’s is refused, because it could never be launched under this app. The dashboard then says which app the file is. When you already have an app with that bundle identifier or package name, it offers Upload to that app; otherwise it offers Upload as a new app. Either way it uploads the same file and opens the app. If that exact file was already uploaded there, no new build is created and the message says so. From the CLI, vibeview upload-app <file> does the same. Let your agent do it works here too; it watches every app, so a build the agent uploads to another app is reported under that app’s name.

If VibeView can’t run an upload on any of its devices, the upload is refused and the upload dialog shows the reason and how to fix it; the CLI prints the same and exits with an error. See When an upload is refused. Starting a session is also refused up front, with the reason, when none of the app’s builds can run, or when no VibeView device can run the build.

Storage limits

Every plan includes a fixed amount of build storage, shared across all apps in your organization:

Uploaded builds and kept production build downloads count toward it; icons do not. When the limit is reached, new uploads (from the dashboard, the CLI, or CI) and new cloud builds are refused with the message “Storage limit reached (25 GB). Delete old builds or upgrade your plan.” (the number is your plan’s limit). Nothing is deleted automatically. A cloud build that was already accepted always keeps its output, and that output counts toward storage. Re-uploading the same build — the same app, version, and build number — never uses extra space; the same file under a new version or on a second app is stored and counted again. Track usage under Settings → Plan and usage, and free space with the Delete build (trash) icon on a Build history row or by deleting the app. For larger allowances, contact support@vibeview.io.

Build notes

Each build carries an optional note. Enter it in the Note (optional) textarea of the upload modal after you select a file. Short, specific notes are the most useful — they surface alongside the version in the Build history table and on test run detail pages so you can tell builds apart at a glance.

You can also edit a note after upload. On the app detail page, click the Note cell on any row in the Build history table to edit in place. Press Enter or click away to save; press Esc to cancel. Clearing the field and saving removes the note. Editing requires the Developer or Admin role; viewers see notes read-only.

Examples of useful notes:

• Fix login crash — hotfix for ticket #1234
• Pre-release with feature flag X enabled
• Reverted notifications refactor

Notes are shown in the Note column of the app’s Build history table (truncated with hover preview) and, when a build is used in a test run, surfaced as hover text on the Build pill on the run detail page.

Run a specific build on a device

Each row in the Build history table has a Play icon labelled Run with this build. Clicking it opens Devices with the chosen build pre-selected for install. A build that a session is running right now carries a tag beside its Play icon:

• Live — your session is running it. Its Play icon opens Devices, where the session is listed under Running.
• Live · CLI / Live · Agent — your session is running it, driven by the VibeView CLI or an AI agent. It is listed under Running on Devices too.
• In use — someone else’s session is running it: a visitor on an embed or share link, a test run, or a teammate. Hover the tag to see which. Its Play icon starts a new session as usual. Worth checking before you delete or replace the build.

The Delete build (trash) icon is shown to Developers and Admins only; Viewers can run and download builds but not delete them.

The session page records the pinned build in the URL as a buildId query parameter, so you can link directly to “start a session against this exact build”:

/sandbox?appId=<app-public-id>&buildId=<build-id>

<build-id> is the numeric AppBuild id (integer). If the parameter is omitted, the page defaults to the app’s latest build.

Same app on other platforms

If your product ships as several apps (for example iOS, Android, Apple TV, Android TV and Roku), link them so the Tests page lists them as one product. VibeView suggests apps that look like the same product; nothing is linked until you confirm it.

• Under the panel, the app page shows which platforms it is linked to, for example “Linked: iOS, Android”, or “Not linked to other platforms”.
• Edit links (or Link apps on an app that isn’t linked yet) opens the full list: Link next to a suggestion, or pick an app from Link another app. A product has one app per platform, and an app belongs to one product. A link that breaks either rule is refused with the reason. You can also link from Review and link on the Apps list.
• Linking shares test data. When apps are linked, their test data becomes one set for the product:
  • A value that exists on only one of the apps, or is the same on all of them, is shared by every linked app.
  • A value that differs keeps a value of its own on that platform. The app you linked from provides the shared value.
  • A secret stays a secret: if the same value is secret on one app and plain on another, the shared value is secret.
  • Environments with the same name become one environment, merged the same way. An environment that only one app had is added to the others.
  • Notes stay separate: each app’s notes stay its own, and the product’s shared notes start empty.
  • If the apps save new paths differently, every linked app gets the stricter setting (Never, then Ask me first, then Save automatically).
  • A message after linking says how many values are shared and which ones kept a value per platform.
  • A link that would give the product more than 200 test data values or more than 50 environments is refused. Remove some first.
• Remove from family unlinks this app after you confirm. It keeps its own copy of the product’s test data, notes and environments, so its tests keep the same values. Its builds, tests and runs stay as they are. Schedules of the product stop running on this app’s devices: a schedule that keeps other devices goes on running on them and its owner is told which devices it lost; a schedule left with nothing to run is paused and its owner is told. The confirmation says so when a schedule will be affected.
• A test can join a group made from another app of its product, as long as both are phone and tablet apps or both are TV apps. A test recorded on Android can go into a group created from iOS. Removing an app from the product keeps the groups its tests are already in.
• Each app keeps its own builds. Linking never changes an app’s platform.
• Phone and tablet apps and TV apps can be in the same product. Their tests are listed separately, and a phone test never runs on a TV.

Viewers can see linked apps; developers and admins can link and unlink them.

Tests

The Tests button on an app’s page opens the Tests page for that app, with its tests, groups, runs, notes and test data.

Deleting an App

Deleting an app removes the app record and all of its builds permanently. This action cannot be undone, and a confirmation dialog always appears before anything is deleted. The app’s tests and groups are not deleted; they stay under No app on the Tests page, and its schedules are deleted.

When the app is linked to the same product on another platform of its form factor, its tests, groups and schedules move to that app instead (for an iOS app, the product’s Android app), so they stay in the product. The confirmation names the app they move to. The moved schedules no longer use the deleted app’s devices.

Tips

• Upload a new build each time you cut a release so you can run tests against any version.
• Use the Note field to label milestones like release candidate or regression baseline so they’re easy to spot in the Build history table.
• Keep one app entry per product rather than creating separate entries for each version — the Build history table handles versioning for you.
• If an upload fails validation, double-check that the file is a genuine .zip/.tar.gz/.tgz archive containing your .app, or a genuine .apk, and is under the 500 MB limit. See Preparing Your App Build.