Keeping It Healthy

Freddy's window works. The last chapter is the one that keeps it working: where everything is kept, what to change and what to leave, what an update does to a Mac with agents running, and the few problems that account for most of the questions.

The problem

A tool you leave running all day, that updates itself, that starts other programs and that holds your conversations is a tool you should be able to reason about. Where is the data? What does an update do while an agent is mid-turn? What does the app send over the network, and to whom?

The hard way

Finding out by accident: the update that restarted the app in the middle of a turn, the crash log you did not know existed, the setting you changed to fix one thing and then forgot. Each one is small. Together they are the difference between a tool you trust and one you work around.

Where your data lives

Everything is stored in ~/.elyra:

Path	Contents
state.db	Projects, threads, conversations, settings, automations, tasks, paired clients and the audit log (SQLite)
worktrees/	Worktrees Elyra created for threads
chats/	The scratch folder used by chats without a project
themes/	Your custom themes
keybindings.json	Your shortcut overrides, if any
logs/crash.log	Details of crashes

Checkpoints (chapter 4) are hidden Git references (refs/elyra/…) inside each project's repository, and deleting a thread removes them. To run a separate copy with its own data, for example to try something out, set ELYRA_HOME:

ELYRA_HOME=~/elyra-test "/Applications/Elyra Workspace.app/Contents/MacOS/elyra"

Settings

⌘,, the gear in the title bar, or Elyra Workspace → Settings…. Changes apply right away and are saved automatically, there is a search field, and every page except Agents & MCP has a reset button. Seven pages:

• General: the external editor (⌘O), updates, and Phone (chapter 13).
• Appearance: color theme (Default Dark, Default Light, Tokyo Night, Palenight, Material, Dracula, Nord, and your own from ~/.elyra/themes), following the system appearance, interface font, conversation width (default 860 points; 0 uses the full width) and density. ⇧⌘T switches theme by hand, which turns Follow system appearance off.
• Code: the font for diffs, the editor and code in the conversation, and Conventional format (chapter 5).
• Terminal: font, cursor, shell, scrollback and the Option key (chapter 11).
• Providers: next section.
• Agents & MCP: the gateway (chapter 14), the Grove settings (chapter 7), automatic turns per goal and automatic fixes (chapter 9).
• Félagi: the connection and running Félagi's agents here (chapter 12).

Some defaults are not on a settings page; Workspace takes them from what you do. New threads use the agent, model, effort and permission mode you chose last, and the open tabs, window size and position, sidebar and tools panel, the open tool tab, collapsed projects and the selected space are restored at launch.

Providers

A provider is the coding agent that runs a thread. Workspace drives the command-line tools you install yourself and does not need API keys of its own. Sign-in, billing and limits are handled by each tool. They are not equal, and the table is worth a read:

Provider	Approvals	Effort	Fork	Gateway
Claude Code	yes	low – max	yes	yes
Codex	yes	minimal – extra high	yes	yes
Elyra	no (tools run directly)	off – extra high	yes	yes (0.9.46 or later)
Pi	no	off – extra high	yes	no
Gemini CLI, Cursor Agent, OpenCode, custom (ACP)	yes	—	via context	yes

Fork via context means a fork sends the earlier conversation along with its first message, instead of branching the agent's own session (chapter 6). Claude Code is the most complete integration: its slash commands, skills and subagents appear under / and @, plan mode shows the plan as a card, its questions appear as forms, and cost per turn is supported. For Codex, the permission mode maps to its approval policy and sandbox, so Full access becomes never-ask and danger-full-access, and Plan only becomes read-only.

Settings → Providers has one section per provider: its status and version, Sign in… (which opens Terminal with the login command), whether it is enabled, its executable if it is not on your PATH, arguments (ACP agents), extra environment variables, accounts, and the escalation model from chapter 9. Changes apply to agents started afterwards.

Accounts let you use several logins for the same agent, for example work and personal Claude subscriptions. Each is a name and environment variables, separated by semicolons:

work: CLAUDE_CONFIG_DIR=~/.claude-work; personal: CLAUDE_CONFIG_DIR=~/.claude

Pick the account before the first message; a session stays with the account that started it. To log in to a new account, run the agent's login with that account's environment, for Claude Code CLAUDE_CONFIG_DIR=~/.claude-work claude, then /login.

One more thing the table hides: Workspace uses the thread's provider to write thread titles, commit messages, pull request descriptions and recaps. Claude Code uses its fast model for this. If the provider cannot do it, Workspace falls back to Claude Code, then Elyra, if installed.

Updates

Elyra Workspace updates itself:

1. At launch and every six hours, it checks GitHub for a newer release.
2. It downloads the new version in the background and checks it: the SHA-256 checksum must match, the app must be signed by the same Developer ID team as the copy you run, Gatekeeper must accept its notarization, and it must report the expected version.
3. A notification says the new version is ready. Click it to restart into the new version. If agents are still working, you choose: Restart when they finish waits and restarts by itself once no turn is running; Restart now stops them, and each thread can be resumed after the update. If you do not click, the update installs the next time you quit.

Elyra Workspace → Check for Updates… checks right away. To download only when you choose, turn off Download and install updates automatically in Settings → General. The app cannot replace itself when it runs straight from the disk image or from a folder you cannot write to; then the notification links to the download instead. Move the app to Applications to get automatic updates.

Going back to the previous version

Each update keeps the version it replaced, hidden beside the app. It is not a second app in Spotlight or Launchpad.

• If a new version does not start: when it fails to get through its first 20 seconds twice in a row (a crash, or it hangs and you force it to quit), Elyra Workspace puts the previous version back and starts it. A notification says so, and the broken version is not offered again; the next release is.
• By hand: command palette (⌘K) → Go back to the previous version…, for when a new version starts but something in it does not work for you. The app restarts as the previous version; running agents stop and can be resumed.

Quitting normally within those 20 seconds counts as a good start. This is the safety net that makes a self-updating app acceptable on a machine that has agents working overnight.

Privacy: what leaves the Mac

• Elyra Workspace has no account and sends no telemetry.
• The requests the app makes itself are the update check and update downloads from GitHub, and two things you turn on: pushes to the ntfy server you choose, if you enable Phone (chapter 13), and your Félagi workspace, if you connect it (chapter 12). The browser tab loads the pages you open in it, like any browser.
• Your messages and files go to the agents you use, under their own terms. Workspace starts them as local programs.
• The gateway listens only on 127.0.0.1 and requires a token (chapter 14).
• Pull requests, issues and other text from outside are marked for the agent as reference, not instructions (chapter 5).

Shortcuts

Press ⌘/ to see all shortcuts, including any you changed. To change them, press Edit… in that sheet: it creates ~/.elyra/keybindings.json with every shortcut's id and default keys and opens it. Change the keys you want, delete the lines you do not need, and restart Workspace. Keys are written like cmd-shift-p, ctrl-tab or alt-down, and null removes a shortcut.

The problems that come up

Symptom	What to do
An agent is listed as “not installed”	Workspace looks on your login shell's PATH and in the common install folders. Check Settings → Providers → Status; if it says Not found, set the full path under Executable.
The agent says it is not logged in, or fails at once	Press Sign in… in Settings → Providers, or run the agent once in a terminal. With accounts, sign in with that account's environment.
“Elyra Workspace is already running”	Only one copy runs per data folder. Switch to the open window, or use a different ELYRA_HOME.
A thread says the last turn was interrupted	The app quit while the agent was working. Resume or Dismiss. Next time, choose Quit when they finish (chapter 13).
The Changes tab says the folder is not a Git repository	Diffs, checkpoints, worktrees and pull requests need Git. Run git init in the project, or use it without those features.
The PR tab or review inbox shows nothing	They need the GitHub CLI: install it and run gh auth login. The project's remote must be on GitHub.
An automation did not run	Automations only run while the app is open. Check that it is switched on and look at its run history; a run is Skipped if the previous one is still going, and a run that waits for an approval is in its thread.
Option+key in the terminal does not type [ or @	Turn off Use Option as Meta key in Settings → Terminal.
After a crash	At the next launch Workspace shows a notice. Click it to open ~/.elyra/logs/crash.log, and include it when you report a problem.

What Freddy's week looks like now

He does not work harder than he did with four terminal tabs; he works with more of it visible. Monday morning, While you were away shows what the weekend's automations did, and the dependency run is a thread with a diff he reads at Agent turns scope. He starts the day's three tasks as three threads, two with their own worktree, and sets a check command so that finished means green. One of them is a goal with a budget. He asks for a flow to be tried in the browser and saved as a journey. He leaves a thread to Quit when they finish at five, and gets a push on the way home that says it passed.

None of that needs the agent to be cleverer than it was. It needs the work to be somewhere you can see it, to be able to be undone, and to be checked by something other than the agent's word. Those are the three things the first chapter promised, and the fourteen since have been the same three, looked at from different sides.

What you learned

• Where Workspace keeps its data, and how to run a separate copy
• What each Settings page is for
• How the providers differ, and what accounts are for
• How an update verifies itself, and how it goes back to the previous version
• What leaves the Mac, and which of those you turn on yourself
• The problems that come up most, and what to do about each