Install & Sign In

Qubis is a native desktop application. Installing it gets you the editor, the agent, the bundled Ferro solver, and navier-solverd — the daemon that runs third-party solvers — in one download.

Supported platforms

Builds are published to releases.qubis.app. Ask your Qubis contact for the download link for your organization if you do not already have one.

macOS

1. Download the .dmg (Apple Silicon only) and open it.
2. Drag Qubis.app onto the Applications folder alias in the window.
3. Eject the disk image and launch Qubis from Applications or Spotlight.

Do not run Qubis from the mounted disk image or from Downloads after unzipping an older archive — macOS App Translocation puts quarantined copies on a read-only mount and the in-app updater refuses to run until the app lives in Applications.

The app is signed with a Qubis Developer ID certificate and notarized by Apple, so Gatekeeper opens it without the "unidentified developer" prompt. If you do see that prompt, the download was interrupted or altered — re-download rather than right-click-opening it.

Windows

Run the .msi and follow the installer. It registers Qubis in the Start menu and installs the programs bundled with Qubis alongside the executable.

Updates are applied by downloading a newer MSI and handing it to msiexec, so an in-app update on Windows will show the standard installer UI.

Linux

Unpack the .tar.gz and run the Qubis binary inside it. Keep the directory intact — Qubis resolves several sidecar binaries (the solver daemon, the CAD mesher, PDFium) relative to its own executable, so moving the binary out on its own will break those features.

First launch

The licence agreement

The first launch shows the end-user licence agreement. You must accept it to continue. Qubis records which version of the text you accepted and only re-prompts when the legal text itself changes — not on every release.

Signing in

Qubis needs an account, and the window is gated until you have one. Once the licence is accepted, a signed-out launch shows only the Qubis lockup and a Log in button. Nothing behind it is reachable: keyboard shortcuts, menu actions, and the editor, viewers and Solver Desk all wait until you are signed in, and closing the window quits rather than asking.

The gate reports the stage it is at:

Signing in is not the end of it on a brand-new account: the gate then reports what the account itself still needs.

Those three middle stages all carry the same three controls: Continue in browser to open the account page where the work is done, Check again to re-read the account once you have done it — Checking… while it is in flight, and Could not check setup. Try again. if that fails — and Sign out.

Log in opens your browser to complete the sign-in and returns you to the app. Signing out from Settings → Account brings the gate back.

The page the browser is left on says how it went. A sign-in that worked reads You’re signed in and leads with Return to Qubis, which brings this build's window forward, with Go to account beside it as a quieter link to your account and billing. One you cancelled reads Sign-in cancelled, and one that failed Couldn’t sign in with the error underneath. Neither carries a button: switch back to Qubis, which is waiting on Log in after a cancel and on Try again after a failure.

A brand-new account finishes in the browser, and that last page offers Open Qubis beside Download Qubis: it brings this Qubis to the front and re-checks the account on the spot, so you do not have to find the window and press Check again yourself. Each release channel registers its own link, so a page from one environment never raises another channel's build. Linux builds ship as a tarball that registers no scheme with the desktop, so neither that link nor Return to Qubis has anything to open there — switch back to Qubis and press Check again.

Once signed in, the Account page shows:

• Your status, and Sign Out.
• Your organization, if your account belongs to more than one. Qubis remembers the organization you pick and restores it on the next sign-in, as long as you are still a member.

Setting up local tools

Signing in takes you straight to the chat: nothing has to be installed up front, and the bundled solvers such as Ferro work as soon as Qubis opens.

When a task needs a program Qubis does not bundle — a container engine for OpenFOAM, Gmsh for meshing, Typst for a PDF report — the agent puts an Install card in the chat under its request. Install puts the program on this machine and the agent carries on once it is found; writing a new message instead lets the agent go on without it. On Linux, tools that need root show Show install command, which opens the command to copy and run.

A card also covers an engine that is installed and simply not running: it reads Start Docker Desktop, Start Podman, Restart Podman, Start Colima or Start OrbStack — whichever provides yours and whatever is wrong with it — and the button starts it, so the agent never starts an engine from the shell. Where Qubis cannot start the one you have the card reads Start the container engine, carries no button, and says how to start it by hand; it carries on once the engine answers. A start that fails offers Try again. See the container engine line.

Settings → Local tools lists every one of these programs with whether it is installed, for installing ahead of time.

The same card covers a plugin the task needs: it reads Install name, then Turn on name, Connect name and Sign in to name as it works through them, so adding a plugin, enabling it and connecting your account happen on the one card. A sign-in that has to be finished off elsewhere — a device code, a token — reads Finish signing in on the Plugins page, with Open Plugins to go there. See Plugins & MCP.

A card that is working says what it is doing — Checking…, Downloading 62%, Installing…, Connecting…, Waiting for sign-in in your browser…, or Waiting for another install… behind one that is already running. One that fails keeps its error and offers Try again, and one whose install needs a relaunch reads Restart to finish.

Environment Setup covers what each tool unlocks and what installing it does on your platform.

What ships in the box

Settings → About lists the programs shipped inside Qubis and whether each was found. This is the fastest way to answer "why is this feature greyed out".

If you want gmsh, press Install when the agent asks for it, or tick it in Settings → Local tools and press Install selected — or install it yourself (brew install gmsh on macOS, your distribution's package on Linux, pip install gmsh anywhere including Windows). Qubis picks it up from PATH either way. On x86_64 Linux Qubis unpacks the upstream static build into its own tools folder, so a newer OCCT from a PPA cannot block it; on other Linux architectures it is one of the installs Qubis leaves to you, with the command shown.

What you still have to install

Two things are not in the box, and Qubis offers to install most of them for you when a task first needs them:

• A container engine. Third-party solvers — OpenFOAM, code_aster, SU2, CalculiX, and the rest — run as containers, so the Solver Desk needs Docker Desktop, Podman, Colima, or an equivalent. Ferro ships with Qubis and needs nothing.
• A handful of optional tools — LibreOffice for previewing PowerPoint decks and Word documents, gmsh for alternative meshing, Typst for typeset reports, Node.js for MCP servers that run locally, language servers for editor diagnostics, the 3DxWare driver for a SpaceMouse.

Environment Setup covers each one per platform, including how to size Docker's CPU, memory, and disk for the cases you actually intend to run. Do that next.

Updating

Qubis checks for updates against a signed manifest and can update itself.

• Command palette → Check for Updates, or Settings → About → Updates.
• When an update is available, Update now downloads and installs it.
• macOS and Linux replace files in place; Windows runs the downloaded MSI and reopens Qubis once the installer succeeds. An install that fails, or one Windows wants a reboot to finish, leaves Qubis closed — start it again yourself.
• On macOS, an account that cannot write to /Applications — a standard user rather than an administrator — gets an administrator prompt reading Qubis wants to install an update. and the swap runs with that approval. Dismiss it and nothing is installed: the update reports Administrator approval was cancelled, so the update was not installed. and you can run it again.

Builds come from one of two channels — stable or dev — fixed at build time. A dev build only ever updates to dev builds, and vice versa; switching channels means installing the other build.