Troubleshooting

Find the symptom, check what the app reports, and follow the recovery steps.

Start with Setup & diagnostics. Installation, login, permissions and project checks are separate: a successful result in one does not prove the others work.

Start with Setup & diagnostics

Open Help → Setup & diagnostics, choose your project and agent, then click Check setup. The checks cover folder access, Git, CLI version, configured MCP connections, the Browser and the test engine. A successful setup check does not prove that your project works. The separate Test CLI button makes a real request using your provider account.

For support, choose Preview support report. Review the JSON before saving it. It contains the running build identity, resource counters, permission preflight and cached CLI/engine checks with their age. Export does not start new CLI or engine probes. Missing checks remain unknown; an available native payload does not mean permission was granted or a physical action succeeded.

Only built-in CLIs checked in the current app process appear in the report. Versions contain the numeric release core; custom names, paths, credentials, raw errors, transcripts and project contents are excluded. Saving writes exactly the report you previewed. Nothing is uploaded automatically. Re-run the relevant setup check and create a new preview if you need a fresh sample.

Inspect a local log when needed

The local event log can help explain a failure after the setup checks. It is separate from the filtered support report; inspect its contents before sharing any excerpt.

Embedded newlines are collapsed to ⏎, so every event stays on one line and grep works.

An agent CLI is not detected

Symptom. claude --version works in your terminal, but the CLI shows up grey in Detect installed AI CLIs and DeckSpace will not launch it.

Why. A GUI app launched from Finder or the Dock inherits launchd’s environment, not your shell’s. The minimal PATH it gets has no nvm, asdf, mise, Homebrew or cargo shims in it.

DeckSpace already works around this. Once per app launch it runs $SHELL -lic 'printf %s "$PATH"', merges the result with the directories below, caches the whole thing, and uses it for every pane and every probe.

Three things break that workaround:

Register it by absolute path. Settings → Custom agent CLIs takes a name, a key, and a binary — the binary field accepts either a bare command or a full path such as /usr/local/bin/goose. An absolute path is checked directly and skips PATH resolution entirely.

A pane opens on walk-away and sits there

Symptom. Walk-away is on, the pane launches, the agent starts — and then stops at its own permission prompt and waits for a human who has left.

Why. DeckSpace does not implement autonomy. It passes the flag your CLI publishes for it, and five of the built-in eleven publish none.

Fix. Use one of the six that do have a flag — see What walk-away does for the full table — or register the CLI again under Settings → Custom agent CLIs and fill in the Walk-away flag field yourself. A custom agent with that field empty behaves exactly like the five above.

An agent’s command was refused

Symptom. The agent runs something ordinary and gets back a red line beginning ⚠ DeckSpace, or a plain Operation not permitted.

These are two different mechanisms with two different fixes. Read which message you got.

“DeckSpace guard” / “DeckSpace blocked a destructive git”

Agent-driven panes get OPX_GUARD=1 and a shim directory at the front of PATH holding three files: rm, git and sudo. The shims are inert without that variable, so a pane you typed into yourself is unaffected. They parse arguments rather than matching text, so flag spellings do not slip past.

Fix. The refusal message prints the absolute path of the real binary. Run the command yourself in a pane you opened by hand, or call that absolute path. Deleted work is not gone: look in ~/.opxspace-trash first.

git restore is the entry that surprises people. It is refused unconditionally, including harmless forms like git restore --staged <file>, because the shim keys on the subcommand and not on the flags after it.

“Operation not permitted”

That is the OS sandbox, not DeckSpace. An agent launched into its own pane runs inside a write fence: reads, execution and network are free, all file writes are denied, and writes are then re-allowed in a short list of places.

Everything else is refused by the kernel — whether the agent writes directly, shells out, uses an absolute path, or runs a script. Another repo on the same machine is outside the fence.

Fix. Move the work into the workspace, or turn Confine agent writes off under Settings → Autonomy for the run that legitimately needs to write elsewhere.

There is no sandbox on this machine

The app never offers an update

Open Settings → Updates and press Check for updates. It reports an available version, a successful no-update result, or a connection error. A failed check is not shown as “up to date”. The manual check works even when background checks are switched off.

Background checks run after launch, periodically while the app is awake, and on focus, with a 30-minute minimum interval. Use the visible checkbox to turn them off or on. Nothing installs until you choose Update now; a failed install stays available to retry.

Preview and development builds use manual installation and do not query the public update channel. Linux .deb and .rpm installations also use manual package installation. Download the current package from your delivery link and install it with your package manager. The update panel explains these cases without claiming a successful update check.

Compare the installed version with Updating and the release notes if needed. A detached panel does not run the main window’s automatic check cadence.

The phone remote answers 403

Two entirely different refusals share that status code, and they send you to two different screens. The error.code in the response body is what tells them apart.

Only two categories can produce forbidden_permission, and which one depends on where the order was told to land:

The other refusals a phone can hit:

A gate never reaches the phone

Symptom. Something is clearly waiting for a human on the desktop, and the phone’s approvals list is empty.

Three of the four gate kinds live only inside the DeckSpace window — the Maestro plan gate, the Maestro question wizard, and mission approvals. They are listed where they can be decided, so while the window is closed they are simply absent rather than shown and un-tappable. Reopen the window and the gate reappears with its original timestamp.

The desktop is also given 4 seconds to answer a phone’s request. An overrun is reported as stalled, not failed — approving a plan starts the whole run, so the decision is applied before the answer comes back. Do not tap twice.

Remote will not start

When the server refuses to come up, Settings → Remote gives a reason. Each maps to a specific fix.

If the mode is This machine only, the server answers on 127.0.0.1 and a phone cannot connect to it directly at all. That is the mode working, not failing. See Phone remote.

Recording will not start or Stop is still cleaning up

Click DeckVoice beside Atlas to show the floating pill. Click the pill to expand its controls, then use the microphone to start and stop recording. Choose Type to turn speech into text. The gear opens quick settings for the mode and transcription engine. For the input device, choose All settings… from the gear menu. Opening the pill alone does not start the microphone.

Another Deck app owns the microphone. Stop recording or always-on listening in the named app, wait for it to finish cleaning up, then try again. A compatible DeckSpace and DeckVoice share one capture slot. If you are using an older DeckVoice build, close it first; older builds do not participate in that coordination.

Cleanup is pending. Press Stop again on the same recording. A timeout does not mean the microphone has closed, so starting another recording is refused until cleanup completes. The app reports readiness only after the audio stream starts. Changing the transcription model does not release the microphone.

Transcription failed after Stop. Retry the retained clip before making another recording. Its audio and partial transcript belong to that recording; an older result cannot consume a newer clip. A device warning may still accompany usable audio.

The hold shortcut works, but there is no audio. Shortcut permission, microphone permission and the selected input device are separate checks. Verify the device with push-button recording first, then test the physical hold key. On macOS, review System Settings → Privacy & Security; a granted screen-recording permission does not grant microphone or Accessibility access.

Linux-only failures

Activation and licence

DeckSpace requires a valid licence key and a device-bound activation token for that specific device and licence key. Both are checked offline at every launch.

Smaller things

Still stuck

Preview and save a support report from Setup & diagnostics, then send the reviewed report and a short description of the failure to info@deckspace.dev. Include the steps that caused it. Inspect any additional log excerpt for private information before sharing it.