Troubleshooting and FAQ

An agent won't run

It says it isn't installed, or is signed out

When a session's agent can't run, a card takes the prompter's place. Install runs the install command and shows what it says. Sign in opens a terminal, runs the agent's own sign-in, and opens its sign-in page beside it; approving there is yours to do. Open in terminal types the command into the session's terminal for you to run. Realm checks again when you come back to the window, or press Check again.

Settings ▸ Engines shows every agent's state and the exact command to install or sign in to it. Realm checks an agent again when its last answer is more than 15 minutes old.

Claude says its sign-in expired

An expired Claude sign-in shows as an error in the transcript. Sign in again in a terminal, then send your message again:

claude auth login

It stopped after a while

An agent left idle for 30 minutes is stopped to free its memory. Nothing is lost: your next message starts it again, and it picks up the conversation where it was.

A Codex session won't start in one space

Codex sessions can't run in a sandboxed space in this release. Set the space's Sandbox to No sandbox to use Codex there. A session that can't get the sandbox it was asked for refuses to start rather than running without it.

Messages at the top of the window

If Realm's agent server crashes, Realm starts it again and your windows reconnect to it on their own, with your drafts and panes as they were. A paired iPhone finds the Mac again too. While that happens, a banner across the top of the window says where things stand:

• Connection lost — reconnecting… The window lost its link to Realm's agent server for a moment. It reconnects on its own; Retry tries now.
• The agent server stopped — restarting it… Realm is starting its server again. Wait a moment.
• The agent server isn't answering. The window has stopped trying on its own. Press Restart Realm's server to stop the old one and start it again; the window reconnects once it's up.
• The agent server keeps failing to start It has crashed several times in a row. Press Restart Realm's server to try again, and if that fails too, look at the log it names, ~/Realm/logs/server.log.
• Realm was updated, but the agent server running is the previous version. You chose Keep working when Realm updated. Press Quit & stop agents, then open Realm again to finish the update.

Restarting Realm to update leaves your agents working. When the new version opens while a session or a task is working, it asks Realm was updated. Restart the agent server? with Restart now and Keep working.

Saved passwords

• Realm couldn't read your saved passwords, so it kept the file aside at … and started fresh. Nothing was deleted. Realm found secrets.json unreadable and moved it, unchanged, to a secrets.unreadable-….json beside it in ~/Realm, rather than writing over it. Show in Finder goes to it. The notice is in Settings ▸ Passwords and stays until you dismiss it.
• Realm needs Keychain access to read your saved passwords. macOS's Keychain didn't let Realm open the key that encrypts them. Nothing is wrong with the file and nothing was moved. Press Try again to ask macOS once more.

Computer use isn't working

If an agent can't drive an app, the prompter says so and offers Allow in System Settings. In Settings ▸ Computer use, both grants should read Granted. If one says it isn't honoured, which can happen after an update, press Repair and switch Realm on again in System Settings when it opens. Check, too, that computer use is switched on for the space you're in.

Files and attachments

• Each attachment can be up to 20 MB. A larger one is refused with its size.
• A file an agent wrote outside the space, such as in /tmp, opens read-only.
• A browser download that isn't part of an action you allowed is stopped. More ▸ Downloads in that pane lists it, with Save.

Closing and quitting

Closing the window or pressing ⌘Q leaves your agents working, with Realm in the menu bar. To stop everything, choose Quit Realm & stop agents from that menu; it asks first if a session is still working. Stop all agents stops the agents and leaves Realm in the menu bar.

Linux and Windows

The Linux (AppImage and .deb) and Windows builds of Realm 2.4 are previews. They are unsigned, so Windows SmartScreen warns on first run (choose More info, then Run anyway), and they don't update themselves: install a new version from the releases page. Features that exist only on a Mac, such as computer use, Laya, simulators, the Dock icon and window translucency, aren't shown there. On those systems Ctrl takes the place of ⌘ in every shortcut, and the Super or Windows key takes the place of ⌃.

A copy you built yourself

Releases are signed and notarized, so they open normally. A copy of Realm you built from source without signing it is quarantined when it's copied to another Mac. Open it the first time with right-click ▸ Open, and if macOS says it's damaged, clear the quarantine:

xattr -cr /Applications/Realm.app

Questions

Do I need an API key?

Not for Claude or Codex: you sign in with your own account, as you would to use the agent without Realm, and its usage counts against your plan. A few agents, such as Gemini and DeepSeek, take an API key in their own configuration instead.

Can I use more than one agent?

Yes. Each session runs one agent, and you can have sessions on different agents side by side, in the same space. A session can also hand work to sub-agents on other agents' models.

Does Realm see my code?

Realm runs on your computer and keeps its data there. Your code goes where your agent sends it, which is its own provider, as it would without Realm. See Privacy and your data.

Where are my settings and history?

In ~/Realm on your computer. Privacy and your data lists what each file and folder holds.

How do I see what changed in an update?

The first window after an update shows that version's notes. The gift button on the rail, and Help ▸ What's New, show them again, and the changelog has every release.