Workspaces

1. Sign in to Onyx Cloud, select an organization, and open Workspaces. Choose New application, Mobile application, an available sample, or Import repository.
2. Name the Workspace. New web and mobile apps include a database by default. Under Advanced options → Database, you can select an existing database you maintain or choose No database — add one later. Samples always create their own copy of the sample database.
3. For an import, enter the GitHub repository URL. AI setup detects the application type, frameworks, runtime, and launch commands from the code. Advanced options include the database, branch, and application directory. Connect GitHub before importing a private repository.
4. Choose Create workspace. Follow setup as it prepares the database and managed credentials, generates or imports the code, applies the web or mobile starter’s initial schema when using a database, and starts the private preview.

Generated apps start with a local Git repository; GitHub is optional. Connect it from the toolbar for private imports, pulls, pushes, and draft pull requests. Use a fine-grained token scoped to the repositories and actions you need, saved through the connection dialog.

Setup requires an available workspace runtime and the permissions shown in the dashboard. Queued setup waits for the runtime; if a step fails, correct the reported issue and retry setup. AI coding tasks additionally need an available model account.

When importing this platform’s repository, choose the Onyx monorepo (Node.js + Java) runtime and No database — add one later. Configure Firebase in Environments after import, then start Preview; this runtime does not start it automatically.

Choose New task and describe a feature, bug fix, or other coding task. Select an available model and thinking level. Tasks use Onyx models by default; connecting ChatGPT from the toolbar switches new tasks to the connected account’s Codex models and allowance. Disconnect it to return to Onyx models.

Follow the agent’s progress, review its changed files and diff, and use Follow up to refine the result. Open task history from the toolbar to return to earlier conversations. Tasks and saved progress remain available when you leave or refresh the page.

You can queue a new task while another task runs. Tasks share the checkout and execute in order. Use the stop control to cancel active work, or Continue task when an interrupted task is waiting for input.

Workspace tasks edit application files. Review their changes and select Save Changes in Code. Beyond the starter’s automatic setup, schema changes and migration application are separate environment actions that you review and run explicitly.

Select Code → Save Changes to save everything with one click. Onyx commits your edits, merges incoming GitHub updates, resolves overlapping changes automatically, and pushes the result to GitHub.

Without GitHub, Save Changes creates a local checkpoint. To connect a remote later, create an empty GitHub repository, connect your GitHub account, and use Code → Connect repository while operations are idle. Your existing checkout and history are retained.

Advanced options contains file inspection, branch selection, draft pull requests, and checkpoint restore. Separate Commit, Pull latest, and Push buttons are no longer needed.

Saving rebuilds an active development preview when the revision changes. A save to GitHub can succeed even if application startup fails; check the preview result separately. Use Preview → Rebuild after resolving dependency or build errors.

Checkpoint restore lets you select specific files to recover. Resolve uncommitted changes in those target files before restoring. Restoring code does not reverse database migrations or change a running deployment.

The development environment uses the database created or selected during setup, unless you chose to add one later. Add staging, production, or custom environments and explicitly bind the database each application should use. Provision additional databases through the Databases section.

Users with organization administrator and database maintainer permissions can provision application and migration credentials. Eligible creators receive these automatically for the initial development environment; otherwise, an authorized administrator must provision them.

Keep ordinary settings in public configuration and server credentials in environment secrets. Application and migration credentials are managed separately. Credential rotation refreshes running services with the new bindings; revocation stops those services until credentials are replaced and the services restarted.

Provisioned Onyx credentials are injected into application servers automatically. Database features should read live data through authenticated server routes using the environment’s bindings. Keep credentials out of browser and mobile code, and verify data access through the running application. An agent’s successful data query does not verify the preview’s connection.

Cloning an environment copies its configuration structure and provider choices. It clears database and Firebase bindings, secrets, and deployment history. Bind the clone’s resources and provision new credentials. Copying database contents uses the separate database clone workflow.

The generated starters use your verified Workspace session in private browser previews, so Firebase setup is not required for their first preview. Configure Firebase before publishing a database-backed starter or connecting its native mobile app to a deployed backend.

1. Open Firebase Auth and choose the environment.
2. Create or select a Firebase project and web app in the Firebase console. Paste its web configuration into the guided setup.
3. Select the sign-in methods and enable the corresponding providers in Firebase. Complete any required provider configuration.
4. Upload the matching service account JSON through the credentials step. It is stored as an encrypted environment secret.
5. Authorize your preview and application domains in Firebase, restart the preview or redeploy, and test sign-in.

Firebase web configuration is public; its service account is a separate server secret. Saving configuration does not create Firebase projects, enable providers, or verify live sign-in. The starters consume these settings; imported applications must implement their chosen authentication flow.

Starter setup prepares the initial schema and starts Preview automatically. Imported apps use their configured commands and may need additional environment setup. For later schema changes, commit the migration, then use the schema controls in Environments to inspect, validate, and explicitly apply it.

In Preview, choose an environment and start or reconnect to its private application. Switch between Desktop, Tablet, and Mobile viewport sizes, or use Open preview for a separate tab. These viewport controls test the browser layout; native builds are managed in Mobile releases.

Hot reload depends on the application’s development server. The web starter rebuilds changed files and needs a browser refresh. Successful coding tasks that change files restart an existing development preview. Use Rebuild to reinstall dependencies, run the configured build command, and restart from the current checkout.

Use Refresh preview logs to inspect startup failures. Saved startup logs remain available after a failed container is removed; the panel distinguishes loading, errors, and empty results. Fix the reported issue, then start or rebuild again.

If controls are unavailable, check runtime connectivity, credentials, and environment setup. If embedding is blocked by browser cookie settings, open the authenticated preview in a separate tab. Idle previews shut down after the configured timeout while retaining the checkout. A private preview is separate from a published application release.

1. Review and commit application changes. Publication uses the latest commit on the checked-out branch unless you select a specific full commit SHA.
2. Choose the release environment, review schema changes, and apply required migrations. Destructive migration steps require explicit approval.
3. Open Deployments and publish the version. Inspect its build, migration, startup, and readiness results. A failed candidate leaves the previous application serving traffic.
4. Prepare the target environment’s database, authentication, secrets, and compatible schema, then promote the tested application image.
5. To recover an application release, choose an earlier image compatible with the current database schema. Review its readiness before switching traffic.

Releases record the commit, image, configuration, and migration versions. Promotion reuses the existing image on the connected runtime. Application rollback does not undo a migration or restore database contents.

Imported projects need a Dockerfile and the schema compatibility and migration commands required by release operations. Stable application hostnames require the deployment’s DNS and HTTPS routing to be configured.

Choose Mobile application at creation, or import a React Native / Expo repository and let AI setup detect its mobile application type. The mobile starter shares its screens across Android, iOS, and the browser preview. Managed native builds support Expo projects with generated native directories and a reproducible root package lockfile.

1. Open Mobile releases and select the release environment. Follow Developer account setup to connect an Expo account and project. In Project and store connections, save the owner, slug, project ID, Android package, iOS bundle identifier, and Expo access token, then choose Verify saved connection.
2. Deploy the backend with Firebase sign-in configured and enter its HTTPS URL as Deployed backend URL. Native apps authenticate against this backend; a private browser preview URL cannot serve as their authenticated backend. Onyx credentials stay on the server.
3. Configure native signing credentials in Expo before the first build. iOS device previews also require devices registered with your Apple development team. Expo project verification checks project access; it does not verify signing or store permissions.
4. Select Save Changes in Code. Choose Device preview, then Build Android or Build iOS. Use Refresh status to check the cloud build and open its Expo logs. A finished preview provides an installation link and QR code. Code changes require a new native build.
5. Choose Store build to prepare a signed store binary. EAS increments platform build numbers; the app version comes from the application configuration. Configure the matching Google Play or Apple developer account and app entry using the setup guide.
6. For a successful store build, choose Submit to Play internal testing or Submit to TestFlight. Android uploads create an internal testing draft to complete and roll out in Play Console. iOS uploads go to App Store Connect for TestFlight processing and any required review.

Store submissions do not publish a public release. Complete listings, screenshots, privacy disclosures, tester requirements, review, and release in the store consoles. Store credentials can be managed by EAS or saved as encrypted environment secrets in Workspaces. Published store links can be saved in Mobile releases.

Mobile builds require a runtime with mobile build support. Build usage is billed to your Expo account; developer accounts and store requirements are managed by Apple and Google. Stopping a Workspace operation does not cancel a cloud build or recall an upload. Check Expo before retrying an interrupted operation.

Refreshing reconnects to persisted operations. After an interrupted agent task, inspect its status and continue from retained files and saved context when offered. Cancel active work from its task controls.

Deleting a conversation removes it from visible history; it does not restore code or roll back releases. Use checkpoint restore, application rollback, and migration recovery for their respective changes.

Use Settings → Clean up runtime when retiring an active Workspace, then delete it. Unstarted setup can be canceled during deletion. Review the retained resources: databases, Firebase projects, GitHub repositories, images, persistent deployment storage, Expo builds, and store applications have separate lifecycles.