builds and safe mode

A workspace's preview runs next to the ixi you use. A build goes one step further: ixi itself runs as built from that workspace, on your real projects. The official build that came with the app always stays installed, so you can go back to it at any time.

the builds panel

In the menu bar choose Customize → Customize ixi…, then Builds under ixi in the sidebar.

Running names the build ixi runs now: official ixi with its version, or one of yours. Below it, each build has a card. Official ixi is the build inside the app. Your own builds are named after the commit they were built from, such as custom-1a2b3c4d5e6f.

tag	means
running	ixi runs this build now
current	the build ixi starts with, when something else is running (safe mode)
previous	the build Roll back returns to
healthy · failed check	the result of its last health check
based on an older ixi	it was built on an older official ixi than the one installed now
migrations not additive	it would remove or rename something in your project data that the official ixi needs

A card of yours also shows its branch and commit, + uncommitted changes if the build included some, when it was built, and the official version it was built on.

button	what it does
Use this build	switch to this build (below)
Open workspace	open the folder it was built from
Bring your changes forward	for a build based on an older ixi (below)
Delete	delete the build, after asking. Its workspace and your projects are kept. You can't delete the build that's running

use a workspace's build

Builds works on the workspace you opened last. With none opened yet, pick one under Use the app as built from. A workspace's card in Builds reads Workspace and its name, with Use this build. Pressing it runs these steps in order, with a live log under the card:

1. Build. A full production build of the workspace, uncommitted changes included. The button reads Building….
2. Check. The build may add to how your projects are stored, but not remove or rename what the official ixi needs. That keeps safe mode working on your data.
3. Back up. Your data folder is copied into backups.
4. Update your data. The build's changes to how projects are stored are applied.
5. Start. ixi restarts on the new build and the window reloads to the dashboard.
6. Health check. ixi checks that the build answers, knows who you are, serves the dashboard, and opens a canvas. For that last check it makes a canvas named ixi build check and deletes it again.

When every step passes, you'll see "Now running custom-…". The new build is current, and the one before it is previous.

If the build or the check fails, nothing has changed yet: you'll see The build failed. or Not used. with the reason. If Node.js or git is missing, you'll see Can’t build yet. with what to install.

If anything after that fails, ixi rolls back by itself. It restores the backup, starts the build that was running before, and tells you where it stopped, for example "It failed its health check — rolled back to official, your data restored from the backup." A dialog says That build failed — ixi is back on and the build's name.

use anyway

When the check refuses a build, the build is kept with the tag migrations not additive, and Use anyway appears on the workspace's card. It asks first: "Its migrations would drop or rename tables or columns the official ixi needs — safe mode might not work on your data afterwards. Use it anyway?" Use this build on the refused build's own card asks before it switches, too. Say yes only if you can live without safe mode on this data.

roll back

Roll back to and a build's name switches back to the previous build. It runs the same backup, start and health check as any switch, and rolls back by itself if those fail.

A rollback you press doesn't restore your data. Projects you changed on the newer build keep those changes.

Use this build on any other card switches to it the same way. On Official ixi, it takes you back to the build that came with the app.

safe mode

Safe mode starts the official ixi instead of your build. Use it when your build won't start, or starts and misbehaves. Your build stays installed and stays current.

how	lasts
hold <kbd>⌥</kbd> while ixi starts	this launch
quit ixi, then start it from Terminal with open -a ixi --args --safe-mode	this launch
your build fails to start, or fails its health check	this launch
your build fails to start twice in a row	until you act

A start that never finished counts as a failure too, for example when you force-quit a hung launch.

In safe mode a dark bar sits at the bottom of the ixi window: Safe mode — running the official ixi build, with the reason: "you held ⌥ at launch", "started with --safe-mode", or your build's name and "failed to start". The Builds panel shows the same banner with the same reason.

button	what it does
Return to custom build	try your build again. If it fails, ixi stays in safe mode
Delete custom build	delete your build, after asking. Its workspace and your projects are kept, and ixi keeps running the official build
Open its workspace	open the folder it was built from, so you or your agent can fix it
✕	hide the bar

Safe mode ends when you return to your build, delete it, or switch to another build.

The official ixi runs on the same projects as your build. That's why a build may only add to how projects are stored.

bring your changes forward

When a newer official ixi is installed, a build made on an older one keeps working. The panel says so: "Your build … is based on ixi …; ixi … is installed. It keeps working until you bring your changes forward."

Bring your changes forward replays the build's workspace branch on top of the newest ixi main. It needs GitHub connected and your fork set up; see bring changes forward. A build doesn't change once it's made, so press Use this build again afterwards to run the result.

limits & good to know

• Building needs Node.js 22 or newer and git on your Mac. The app has no build tools of its own. It uses the node and git your shell finds. When one is missing, the workspace's card says Building needs Node.js and git on your Mac with how to install it, and Use this build stays greyed out. For git, that's Apple's command line tools (xcode-select --install). The workspace's setup script must have finished first, since it installs the packages.
• One build or switch at a time. The buttons are greyed out while one runs.
• ixi keeps 2 of your builds, plus whichever are current and previous. Older ones are deleted after a successful switch.
• Every switch backs up first. These copies share the backups folder with the copies taken before updates, and only the three newest are kept. See where your things live.
• A crash in the middle of a switch isn't undone. The next launch starts the new build on its updated data. Two such crashes in a row lead to safe mode.
• Deleting a build never touches your projects. It removes the build only. The workspace and its branch stay.

related

• customize ixi: make the change in a workspace first.
• github: push your branch, propose it to ixi, and bring it forward onto a newer ixi.
• ixi local: where your projects and backups live.