Troubleshooting & FAQ

This page explains what to do when Bikube or one of its cards doesn't start, connect, resume or sync as expected, and answers common questions.

Installing and launching

macOS blocks the first launch

Bikube isn't signed with an Apple Developer ID, so macOS blocks it the first time you open it. Open System Settings, Privacy & Security, scroll to the message about Bikube and click Open Anyway. Or clear the quarantine flag in a terminal:

xattr -dr com.apple.quarantine /Applications/Bikube.app

After that it opens like any other app, updates included.

The AppImage doesn't start

The AppImage needs FUSE 2. On Debian and Ubuntu:

sudo apt install libfuse2

On Ubuntu 24.04 and later the package is libfuse2t64 instead. Also check that the file is executable (chmod +x).

Running sandboxed on Ubuntu 23.10 and later

Ubuntu 23.10 and later restrict unprivileged user namespaces, which Chromium's sandbox needs. There, the AppImage starts Bikube without that sandbox. Install the .deb instead: it sets up an AppArmor profile so Bikube runs sandboxed. See Install.

Is Windows supported?

No. Bikube runs on macOS on Apple silicon and on Linux x64.

Cards

Couldn't start

Couldn't start means Bikube couldn't run the card's shell at all; the reason follows it:

• working directory not found: the card's folder doesn't exist on this machine, for example a card from another machine through the sync folder whose repository you haven't cloned here, at the same place under your home folder. A worktree card whose worktree folder is gone offers to run in the workspace folder instead.
• The Shell setting points to a program that doesn't exist or can't run: pick Login shell in Settings, Shell.

SSH failed

SSH failed means ssh itself failed, and its last line says why: the host can't be reached, authentication failed, the connection dropped, or the remote folder doesn't exist. Try the same ssh in a terminal (ssh me@devbox), fix what it reports (often ~/.ssh/config or your SSH agent), then open the card again to reconnect. A password or host-key question shows in the card itself; answer it there. See SSH workspaces.

An agent doesn't resume

• Claude Code resumes the card's conversation only once you have sent it a message; before that, every start is fresh. A conversation that no longer exists on this machine starts fresh with the same id.
• Codex, Gemini CLI, OpenCode and Pi resume the latest session in the card's folder. Two cards with the same agent in one folder share it; give each its own worktree to keep them apart.
• A card new to this machine through the sync folder starts its local agent fresh, since its conversation is on the machine that ran it.
• Moving a card to its own worktree, or removing its worktree, starts a new session in the new folder.
• (not installed) next to an agent means your login shell can't find its command; install it, or fix your PATH in your shell profile.

See Agents & resume.

A pending worktree fails

When a card created with board create --worktree is first opened and git can't make its worktree (the branch was created meanwhile, the folder is no longer a git repository), the card shows Couldn't make its worktree and git's reason. Fix the cause and click Retry, or click Run in workspace folder to drop the worktree and run the card in the workspace folder. See Worktrees & git.

A worktree card's setup fails

The card shows Setup failed and its agent doesn't start. Read the error in the card's terminal, fix it there, then pick Retry setup in the card's menu, or Skip setup to start the agent anyway.

The board command

board: command not found

board exists only inside a Bikube card's shell and its panes, not in your other terminals. Inside a card, it is missing when your shell profile reorders PATH, as macOS's path_helper does in a login shell. Call it through $BIKUBE_BIN, which always points to it:

"$BIKUBE_BIN/board" list

Run outside a card by its full path, it answers board: not running inside a Bikube card. With Bikube closed, board: Bikube is not running.

board in an SSH card can't reach Bikube

• board: can't reach Bikube from this host: the host refused the socket forwarding, usually because its sshd_config sets AllowStreamLocalForwarding no. The card keeps running; ssh printed a warning about it when the session started. Ask the host's admin to allow it, or use board from local cards.
• board: needs perl or python3 on this host: install either on the host.

See The board command.

Sync

Sync folder unavailable or Sync file unreadable

• Sync folder unavailable: the sync folder is missing or can't be read or written, for example a drive that isn't mounted or a sync tool that removed the folder. Your changes stay on this machine, and Bikube syncs again as soon as the folder is back. To stop, turn the sync folder off in Settings, Sync.
• Sync file unreadable: bikube-board.json is damaged, or was written by a newer Bikube. Bikube never overwrites it. Update Bikube on this machine if another one is newer; otherwise restore the file from your sync tool's history, or delete it, and Bikube writes this machine's board there again.

Running cards are never stopped or removed by a sync. See Sync folder.

Updates

Bikube doesn't update itself

With the .deb, Bikube links to the release instead of installing it: download the new .deb and install it with apt. An AppImage in a folder you can't write does the same. See Updates.

Questions

Does Bikube send my code or data anywhere?

No. Bikube has no account, server or telemetry. It talks to GitHub only to check for updates, and with your own gh for pull request status when you have it. Your agents talk to their own services as they always do.

Where are my board and settings?

In plain files in Bikube's data folder; see Where Bikube stores its data.

Does closing Bikube stop my agents?

Yes. Quitting stops every card and shell. Your board stays, and opening a card again resumes its agent's session, with its earlier output shown above.