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 local Git; GitHub is optional. Open the GitHub connection dialog in the toolbar or Integrations and choose Sign in with GitHub. Open the GitHub page, enter the one-time code, and authorize access. Onyx updates the dialog when connected. For an account that cannot use browser sign-in, expand Use a personal access token instead and supply a fine-grained token scoped to the repositories and actions you need. Private imports, pulls, pushes, and draft pull requests require the corresponding GitHub access.

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 No database — add one later. Connect GitHub for a private repository and use an available Onyx model or connected AI account. AI setup detects the stack and configures launch commands before starting Preview. Follow its instructions for Firebase or other missing services; no special runtime selection is required in the import form.

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.

Attach images or UTF-8 text files with the paperclip, or paste a screenshot into the composer. Use these references to describe a layout, share requirements, or explain a bug. Dictation is also available in supported browsers.

Keep AI chat and the live preview together, resize the panels, and open changed files or diffs alongside the conversation.

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 messages while work runs. In the queue above the composer, edit a message, reorder it by dragging its grip or using the arrow keys, or cancel it before it starts. Choose Interrupt to deliver a queued message and its attachments to the running chat using that turn’s model and permissions. Queue changes are saved on the server and work continues with the browser closed. Use the stop control to cancel active work, or Continue task when an interrupted task is waiting for input.

Describe the application outcome in Tasks. With schema-update permission, the agent can implement, publish, and verify the required development schema in the same task; record writes and backfills need mutation permission too. Review the changed files and save the work. For applications with the versioned migration manifest, saved database updates run automatically during code sync, deployment, and promotion. Missing permission is reported in the task.

Use Save beneath a completed task to preserve the work. With GitHub connected, Onyx commits edits, brings in remote updates, and pushes the result. Overlapping edits use AI-assisted conflict resolution; inspect reported failures before retrying. Branch protection and team review requirements still apply.

Without GitHub, saving creates a local checkpoint. To add a remote, create an empty GitHub repository, connect your account, and use Connect repository in the workspace’s GitHub settings while operations are idle. Your existing checkout and history are retained.

Use Environments → Change branch to select a branch. Open files and task diffs beside chat. You can also ask the agent to create a draft pull request or restore selected files with the appropriate Git permissions.

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.

Enable Team reviews in workspace settings to require teammate approvals before syncing changes into organization environments. Set the required approval count; approvals apply to the current saved changes.

Work in a cloned environment on a feature branch, then request a review of the changes you want to sync. Teammates can compare files, comment on specific lines, approve, or request changes. Reviews are available inside Onyx with or without GitHub.

Use Ask AI to resolve feedback to turn review comments into a task. Update the review after making changes, collect the required approvals, and sync the reviewed version into the target environment.

Open Agent permissions in settings to choose workspace defaults or permissions for the selected environment. Environments inherit workspace defaults until you save their own settings.

Use the permission control in the task composer to choose the access available to that task. Onyx resource permissions and Git write access are separate. Available permissions are limited by your own access; Git writes can be enabled without a connected database.

Open Domains and DNS in settings and connect Cloudflare. Add an existing domain or select a domain already in your account, then attach an application address to the appropriate environment. The panel also lets you manage DNS records.

You can search for a new domain or transfer an existing one to Cloudflare. Registration and transfer require confirmation of live availability, pricing, and charges. For an existing domain, complete the nameserver changes at its registrar when requested.

A domain binding does not publish your application. Prepare the environment, deploy the app, and verify its address and authentication settings before sharing it.

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 copies current application files, persistent local data, public configuration, and eligible encrypted secrets. For an attached Onyx database, Clone database is the default: it copies data, schema, saved queries, and scripts into an independent database. You can instead create an empty database or share the source database. Without a source database, choose no database or a new empty one. Each database-backed clone gets separate managed Onyx credentials. Firebase and other external services can remain shared; connect Stripe separately in the cloned environment. The clone queues behind preceding work and stops the source application while copying. Runtime containers and sessions start fresh.

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. Imported apps use AI-detected launch commands and may need additional service setup. Ask the agent for later schema changes and grant the required access. Apps with the versioned migration manifest apply their saved migrations automatically when code is synced or published to an environment.

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. Open Tests beside Preview and chat. Describe a flow in chat, such as “Create Playwright tests for sign-in and ticket ownership.” Successful test-creation tasks queue a run automatically.
2. Choose Run all to run the saved suite for the selected environment, or Cancel run to stop it.
3. Watch the browser frames, inspect passed, failed, and skipped results, and open assertion errors or source files. Ask the agent to fix the failing flow and run the suite again.
4. Use test run history to revisit results. Runs continue when you close the tab; the latest 30 runs remain available for the environment.

The runtime supplies Playwright and Chromium. Tests still use your application’s own authentication. If execution is unavailable, saved suites remain visible; ask your Onyx administrator to enable testing on the hosting runtime.

Open Integrations → Marketplace to see Cloudflare, GitHub, ChatGPT, Firebase, and Stripe connections. Check the scope shown on each connection: Firebase and Stripe reflect the selected environment, while other account connections may be shared.

1. Select Stripe for the environment that will run your app. Start in test mode; select live mode explicitly when ready.
2. Save a Stripe secret or restricted key and its matching publishable key from the same account and mode. Restricted keys need Account read permission and the permissions required by your app.
3. If your app implements a webhook endpoint, add that endpoint’s signing secret. Connecting Stripe supplies credentials; ask the agent to implement and test checkout, subscriptions, and webhook handling for your app.
4. Restart Preview or redeploy after connecting, changing, or disconnecting Stripe. Existing running releases keep their current bindings until replaced.

Keys are verified and stored as encrypted environment bindings. Connect Stripe separately for a cloned environment. This connection handles payments in your application; manage your Onyx subscription from Organizations.

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 and check its database, authentication, and secrets. For apps with the versioned migration manifest, Onyx runs the committed migrations automatically. Imported apps need compatible release and migration configuration.
3. Open Deployments and publish the version. Inspect the build, database snapshot, database update, startup, readiness, and recovery stages shown for that environment.
4. Prepare the target environment’s database, authentication, and secrets, then promote the tested application image. Supported migrations run against the target database.
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. Shared staging, production, and custom environments with an Onyx database pause the current application and snapshot database contents and schema before applying changes and checking the candidate. Plan for this maintenance interval. If the release fails before cutover, Onyx restores the snapshot, schema, migration journal, and previous application; this also undoes database writes since the snapshot. Personal and development environments use a different release flow.

If automatic recovery is incomplete, traffic stays paused and the release reports that recovery needs attention. An administrator must restore runtime connectivity and restart the worker so recovery can resume. A successful release with pending migration cleanup needs that cleanup completed through an authorized task. Choosing an older application image separately checks schema compatibility; it does not undo historical migrations or restore past database contents. Imported projects need a Dockerfile and suitable release configuration. Configure DNS and HTTPS routing for a stable application address.

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. Save the application changes from the task. 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 Delete workspace in Settings when retiring a Workspace. Deletion cancels active operations and removes its running containers and checkout; failed cleanup retains the workspace for retry. Save and push work you need first. Databases, Firebase projects, GitHub repositories, images, persistent deployment storage, Expo builds, and store applications have separate lifecycles; review the retained resources before confirming.