> ## Documentation Index
> Fetch the complete documentation index at: https://docs.autosana.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Apps
> Upload and manage your apps and websites in Autosana
Before you can run any flows, you need to add your app or website to Autosana.
## What is an App?
In Autosana, an **app** represents something you want to test - this can be a mobile app (iOS or Android) or a website.
### Key Concepts
* **App**: A mobile application or website you want to test
* **Chrome Extension**: An optional dependency included in web flow runs
* **Build**: A specific version of your mobile app (.app for iOS, APK for Android, or a url for a website)
* **Active Build**: The build that will be used when running flows
* **Environment**: Optional grouping to organize apps (e.g., Development, Staging, Production)
## Creating a New App
### Step 1: Navigate to Apps Page
Click on **[Apps](https://autosana.ai/apps)** in the sidebar navigation.
### Step 2: Click "Create New App"
Click the **Create New App** button in the top right corner.
### Step 3: Fill in App Details
**Required Fields:**
* **App Name**: A descriptive name for your app (e.g., "MyApp iOS")
* **Bundle ID**: Your app's unique identifier (e.g., `com.company.appname`)
**Optional Fields:**
* **App ID** (iOS and Android): Expand **App ID (optional)** to set one. Only needed to keep several apps with the same bundle ID in one environment, for example one per release version.
* **Environment**: Assign the app to an environment for better organization
* **Agent Context**: Add special instructions for the agent (e.g., "The app requires biometric authentication on first launch")
[Learn more about finding your Bundle ID →](/bundle-id)
### Step 4: Select Platform and Upload
Choose your app's platform and provide the required build or URL:
**Upload Requirements:**
* For simulator tests, upload a `.zip` containing an `.app` built for iOS Simulator
* For physical-device tests, upload a Development or Ad Hoc signed `.ipa`
* Autosana routes `.zip` / `.app` builds to simulators and `.ipa` builds to real devices
When uploading an IPA whose Team-ID-prefixed Keychain access groups break
after cloud re-signing, expand **Advanced** and enable **Fix Keychain access
after re-signing**. Most apps do not need this option.
[Learn more about simulator and real-device iOS builds →](/app-build-guide)
**Upload Requirements:**
* Drag and drop an `.apk` file
* Ensure the APK includes the `x86_64` architecture (universal APKs are recommended)
* Every Android device includes Google Play services, so no extra setup is needed
[Learn more about building Android apps →](/app-build-guide#android-builds)
**No build file required!**
* Simply enter the URL of your website (e.g., `https://example.com`)
Simply enter your website URL — no build files needed. When triggering a run you can choose between **Chrome** (real Google Chrome — default), **Firefox**, **Edge** (Microsoft Edge), or **Chromium** (open-source, no proprietary codecs / DRM).
[See Web Testing for how each engine differs and when to pick which →](/web-testing)
Add a Manifest V3 extension in either form:
* Paste its Chrome Web Store URL to snapshot the current published version
* Upload a `.zip` containing the unpacked extension directory
Store registration derives the extension name and ID automatically. For a
zip upload, enter a name; the Bundle ID is optional but recommended when CI
will upload future versions of the same extension.
Extension zips may contain `manifest.json` at the archive root or inside one
top-level folder. The compressed archive limit is 500MB. Uploaded extension
archives are stored privately and are only accessed when Autosana runs your tests.
Extensions are organization-wide dependencies, so they do not belong to an
environment and cannot be run directly. Attach them from a web app card or
select them for one run in the Run dialog.
### Step 5: Complete Upload
Click **Upload** and wait for the file to upload. Once complete, your app will appear in the Apps list.
## Managing Builds
Each app can have multiple builds. This allows you to test new versions while keeping previous builds available.
### Uploading a New Build
1. Find your app in the Apps list
2. Click **Upload New Build**
3. Select your new build file
4. Click **Upload**
The new build will automatically become the active build.
### Setting an Active Build
The **active build** is the version used when running flows.
To change the active build:
1. Click **Show build history** on your app card
2. Find the build you want to activate
3. Click **Set as active**
### Downloading Builds
To download a previous build:
1. Click **Show build history**
2. Click the download icon (⬇️) next to any build
### Deleting Builds
To delete a build:
1. Click **Show build history**
2. Click the trash icon (🗑️) next to the build
3. Confirm deletion
If you delete the active build, the next most recent build will automatically become active. If no builds remain, flows cannot run until a new build is uploaded.
## Editing App Details
### Changing App Name
1. Click the pencil icon (✏️) next to your app name
2. Edit the name
3. Press **Enter** or click **Save**
### Adding Agent Context
Agent Context provides special instructions to the agent when running flows on this app.
1. Click **Add Agent Context** (or **Edit Agent Context** if already set)
2. Enter instructions
3. Click **Save**
**Example Agent Context:**
```
This app uses Face ID on first launch.
The test account is test@example.com with password TestPass123.
After login, dismiss the tutorial overlay by tapping "Skip".
```
### Changing Environment
If you use environments to organize your apps:
1. Click the environment dropdown on your app card
2. Select a different environment
## Organizing with Environments
Environments help you organize apps by deployment stage or purpose.
### Creating an Environment
1. Navigate to **[Settings](https://autosana.ai/settings)** → **Environments**
2. Click **Create Environment**
3. Enter a name (e.g., "Staging", "Production", "QA")
4. Click **Create**
### Assigning Apps to Environments
* **During app creation**: Select an environment from the dropdown
* **After creation**: Use the environment dropdown on the app card
* **Via CI/CD**: Pass the `environment` parameter in the [GitHub Action](/ci-cd-integration#step-3-set-up-your-github-workflow-with-the-autosana-github-action) or [Upload API](/api-ci) to automatically assign the app to an environment on upload
Apps grouped by environment appear in separate sections on the Apps page.
If you have release and develop builds that share the same bundle ID, use different environments to keep them as separate apps. See [Assigning Apps to Environments](#assigning-apps-to-environments) above for setup instructions.
To keep several apps with the same bundle ID in one environment, for example one per release version, give each its own App ID. Set it when you create the app, on the app card, or by uploading with an `app-id`. The app card shows it next to the bundle ID. See [Separate apps that share a bundle ID](/ci-cd-integration#separate-apps-that-share-a-bundle-id).
## Troubleshooting
### Common Issues
**iOS:**
* For simulator runs, ensure the `.zip` contains a valid simulator `.app`
* For physical-device runs, upload a Development or Ad Hoc signed `.ipa`
* Do not rename an IPA to `.zip`; the extension determines the target device type
* Verify the bundle ID matches what you entered
**Android:**
* Ensure the APK is properly signed
* Check that the file extension is `.apk`
* Verify the bundle ID matches the package name
**Chrome extensions:**
* Only Manifest V3 extensions are supported
* Upload a `.zip` of the unpacked extension, not a `.crx`
* Keep `manifest.json` at the archive root or inside one top-level folder
* Extension-enabled runs use Chromium
## Next Steps
Now that you've uploaded your app:
* [Create your first flow →](/flows)
* [Set up our CI/CD integration →](/ci-cd-integration)
* [Organize flows with suites →](/suites)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.