> ## Documentation Index
> Fetch the complete documentation index at: https://ona.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Ona Desktop
Ona Desktop is the fastest and easiest way to run and recreate cloud development environments locally. It is currently available for Apple silicon users.
## Benefits
* Run Dev Containers locally, replacing Docker Desktop for local development optimized for Apple Silicon, providing native-like Linux development without the overhead.
* One-click setup, full workload isolation, and the ability to "break it, forget it" - iterate quickly without fear of polluting your system.
* Leverage your local machine's resources for free
* Easily share your configured environments across your team to benefit from the automation and standardization of cloud development environments on your own hardware.
* Through Automations, get an optimized developer experience to launch environments and common development workflows through Ona Automations.
* Stay productive with offline capability and built-in disaster recovery support, seamlessly switching between local and cloud development as needed.
## Setup
### Download
1. [Download Ona Desktop for Apple Silicon](https://ona.com/ona-desktop/download)
2. Open `Ona.dmg` and drag `Ona.app` into the Applications folder
3. Launch Ona from the Applications folder
### Install Runner
When you first launch Ona Desktop, it will guide you through a simple setup process:
1. The app will verify and configure the macOS runner (used to run [environments locally](#local-environments))
2. Wait for the installation to complete
* Note: The "Setting up file system" step may take several minutes
* The progress will show you the current status
{' '}
If you have trouble installing, please check the [troubleshooting guide](#runner-installation-failure).{' '}
## Authentication
To use Ona Desktop, you'll need to connect it with your Ona account:
1. When you first open the app, click **Sign into Ona** in the prompt window. This will open your default browser.
2. Sign in using your Ona account credentials.
3. Once signed in, you can close the browser window and return to Ona Desktop.
4. Ona Desktop should open or you should see a dialog asking you to open.
{' '}
If you have trouble signing in, try to [sign out completely and try again](#switching-accounts).{' '}
## Local Environments
Ona Desktop automatically starts a macOS runner for the current organization, managing local environments.
### Git Authentication
Local environments require Git access to clone repositories. Here's how authentication works:
1. **Git Credentials:** The runner automatically checks your local credential manager for an existing Git token. If found, it's used immediately. Tokens are automatically refreshed when environments restart to maintain access.
2. **Personal Access Token (PAT):** If no token exists, Ona will prompt you to provide a PAT when creating an environment first time. You can manage your PAT under `Settings` -> `Git Authentication`. Click `Authenticate and Create` to proceed.
3. **Connect to Source Control:** Ona Desktop will initiate a connection to your source control provider (e.g., GitHub). Follow along the instructions to grant access to your repositories.
4. **Self-Hosted SCM Providers:** If you use a self-hosted source control provider, administrators must configure it in the organization settings. Members can then authenticate using PATs. See [Configuring Repository Access](#configuring-repository-access).
{' '}
If you encounter Git access issues, try to [invalidate Git authentication](#invalidate-git-authentication).{' '}
### Runner Lifecycle
Each macOS runner is tied to a single organization, and only one runner can be active at a time.
Here's how it works:
* **Stopping the Runner:** Stops all associated local environments.
* **Quitting Ona Desktop:** Automatically stops the runner.
* **Switching Organizations:** The current organization's runner is stopped. The new organization's runner is started.
* **Restarting Ona Desktop:** Starts the runner again.
* **Restarting Environments:** Upon restarting Ona Desktop, you can start local environments again.
### Shared Cache
Local environments use a shared cache for Docker images and builds stored on your local machine. This cache speeds up the creation of new environments and the rebuilding of existing ones.
To clear the cache, select "Help" > "Troubleshooting" > "Clear Cache and Restart" from the menu bar.
Clearing the cache can be useful if the caches are corrupted or you want to start fresh.
## Organization Settings
### Disabling Local Environments
Organization administrators can control the use of local runners (Ona Desktop) across their organization:
1. Navigate to Settings -> Runners -> Ona Desktop in your organization settings
2. Use the toggle to enable or disable local runners for your organization
{' '}
Disabling local runners will immediately stop all running environments on Ona
Desktop and prevent members from starting new local environments. Before disabling,
notify organization members as they will lose access to any active work in local
environments.{' '}
### Configuring Repository Access
Administrators can configure repository access to source control providers for local runners:
1. Navigate to Settings -> Runners -> Ona Desktop
2. Configure authentication for source control providers:
* `github.com` and `gitlab.com` are configured by default
* For self-hosted SCM providers, administrators must add them here before members can authenticate
* Members can then use **Personal Access Tokens** (PAT) to authenticate with configured providers, if they don't have existing Git credentials on their machine
See [Source Control](/docs/ona/source-control/overview) for more information on configuring source control providers.
## Updating
Ona Desktop releases new versions weekly, delivering the latest improvements and features. While the application updates automatically, you can manually check for updates by selecting "Ona" > "Check for Updates..." from the menu bar.
After downloading a new version, Ona Desktop will prompt you to restart the application to apply the update.
### Checking Your Version
To check your current version, select "Ona" > "About Ona Desktop" from the menu bar.
Click "Copy" to save the version information to your clipboard, which can be helpful when [seeking support](#report-issue).
### Switching to Insiders
{' '}
Switching to Insiders is an advanced feature that may cause instability or break
your Ona Desktop installation. Only proceed if you understand the risks.{' '}
Ona Desktop provides nightly builds for testing and feedback purposes. While we recommend using the stable version, accessing Insiders builds can be useful when you want to preview upcoming features before their official release.
To switch to Insiders:
1. Quit Ona Desktop
2. Open your terminal and run: `echo "{\"quality\":\"insider\"}" > ~/Library/Ona/argv.json`
3. Launch Ona Desktop
4. Check for updates to install the latest version
5. Verify the installation by [checking your version](#checking-your-version). You should see "Insider" in the version information.
### Switching to Stable
To return to the stable version from Insiders, follow these steps:
1. Quit Ona Desktop
2. Open your terminal and run: `echo "{\"quality\":\"stable\"}" > ~/Library/Ona/argv.json`
3. Launch Ona Desktop
4. Check for updates to install the latest version
5. Verify the installation by [checking your version](#checking-your-version). You should not see "Insider" in the version information.
To switch back to the stable version, you must wait for a newer stable release to become available, as Ona Desktop does not support downgrading to previous versions.
To revert to a previous stable version:
1. [Uninstall](#uninstall) your current version of Ona Desktop
2. If experiencing compatibility issues, perform a [clean uninstall](#clean-uninstall)
3. [Setup](#setup) Ona Desktop again
## Uninstall
To uninstall Ona Desktop, select "Help" > "Troubleshooting" > "Uninstall" from the menu bar.
This action removes both the local runner and the application.
For a complete removal of all Ona Desktop data, including local environments and settings, perform a [clean uninstall](#clean-uninstall).
### Clean Uninstall
{' '}
Performing a clean uninstall will remove all Ona Desktop data, including your
local environments and settings.{' '}
1. Begin by [resetting Ona Desktop data](#reset-data).
2. When Ona Desktop restarts, do not proceed with the installation. Instead, [uninstall](#uninstall) the application.
## Troubleshooting
If you encounter any issues:
1. Ensure you are [up-to-date](#updating).
2. Restart Ona Desktop, as some errors may be temporary.
3. If you don't have any sensitive local environments, try to [reset the data](#reset-data). This can sometimes resolve issues.
4. If the issue persists, collect diagnostics using "Help" > "Troubleshooting" > "Collect Logs and Diagnostics". Review them for system-specific problems.
5. Start a support chat with us from Support in the organization menu. If it's not available in Ona Desktop, use Ona from the browser.
6. Describe what happened, what you did, and what you expected. Upload the logs and diagnostics, and include any relevant screenshots.
{' '}
Be cautious when sharing logs online, as they may contain sensitive information.{' '}
Resetting data permanently removes all Ona Desktop data, including local environments and user settings.
This action is helpful when Ona Desktop is not functioning correctly or when you want to start with a clean installation.
To reset data, select "Help" > "Troubleshooting" > "Reset and Restart" from the menu bar.
If you encounter installation errors:
1. Check the error message details
2. Make any required system adjustments
3. Restart the installation process
4. If problems continue, [submit an issue report](#report-issue)
To use a different Ona account when signing in:
1. In your default browser, sign in to the Ona account you want to use.
2. In Ona Desktop, select **Sign into Ona** and complete authentication.
3. If the **Switch accounts?** confirmation appears, select **Switch account**.
4. If Ona Desktop keeps using the previous account, log out of Ona Desktop and your browser, then try again.
5. If problems continue, [submit an issue report](#report-issue).
If you're experiencing Git authentication issues, try these steps:
1. Verify if you are using a Personal Access Token (PAT) for runner authentication in `Settings` > `Git Authentication`.
2. If using PAT, invalidate it by clicking `Remove`. Remember to also revoke the PAT in your source control provider, e.g. GitHub.
3. If not using PAT, verify your Git credentials by attempting to clone the repository on your local machine. Update credentials if authentication fails.
4. Restart your local environment to apply the changes.
If your runner unexpectedly fails:
1. Check the error message for specific details
2. Restart Ona Desktop to attempt automatic recovery
3. If the issue persists, try [resetting the data](#reset-data)
4. If problems continue, [submit an issue report](#report-issue)
