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 here
2. Open Ona.dmg and drag Ona.app into the Applications folder
3. Launch Ona from the Applications folder

You can also find it in the Ona dashboard at app.ona.com.

​

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)
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

​

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.
   

   Authentication Prompt
2. Sign in using your Ona account credentials.
   

   Complete Authentication Page
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.
   

   Ona Desktop Open Dialog

​

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.
   

   Ona Desktop Open Dialog
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.
   

   Connect to GitHub
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.

​

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

​

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 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.

​

Switching to Insiders

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. 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. 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 your current version of Ona Desktop
2. If experiencing compatibility issues, perform a clean uninstall
3. 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

1. Begin by resetting Ona Desktop data.
2. When Ona Desktop restarts, do not proceed with the installation. Instead, uninstall the application.

​

Troubleshooting

​

Report Issue

If you encounter any issues:

1. Ensure you are up-to-date.
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. 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 using the bubble icon in the bottom right corner of the application. If it’s not available in Ona Desktop, use Ona from the browser.
   

   Report Issue
6. Describe what happened, what you did, and what you expected. Upload the logs and diagnostics, and include any relevant screenshots.

​

Reset Data

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.

​

Runner Installation Failure

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

​

Switching Accounts

To switch to a different Ona account, follow these steps:

1. Logout from Ona Desktop
2. Logout from your current Ona account in your default browser
3. Launch Ona Desktop and complete the authentication process with your new account credentials
4. If problems continue, submit an issue report

​

Invalidate Git Authentication

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.
   

   Invalidate PAT
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.

​

Unexpected Runner Failure

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
4. If problems continue, submit an issue report