Skip to content

Troubleshooting

Start with sesame-link status and sesame-link doctor, which find and fix most setup problems. If they don’t help, find your symptom:

Check the connection

Section titled “Check the connection”
Terminal window
sesame-link status

The first line says whether this computer is connected. When something needs fixing, the report ends with the command to run next. Add --verbose for more detail, or --json to read the report from a script.

Repair your setup

Section titled “Repair your setup”
Terminal window
sesame-link doctor

doctor checks your setup and configuration, repairs what it can, and gives the command that fixes anything it can’t.

Read the log

Section titled “Read the log”
Terminal window
sesame-link logs            # the log's last lines
sesame-link logs --follow   # keep printing new lines

Common problems

Section titled “Common problems”

A computer is offline

Section titled “A computer is offline”

A computer shows as offline when Sesame Link isn’t running on it or can’t reach the Sesame Link service. Its sessions keep their state in the meantime. Run sesame-link status on the computer, and if Sesame Link isn’t running, start it from the folder you want new sessions to use:

Terminal window
sesame-link start

Sesame Link starts when you log in, so a computer that nobody is logged in to stays offline:

  • On a Mac with FileVault, a restart (such as an overnight macOS update) waits at the unlock screen. Sesame Link reconnects once someone logs in at the Mac.
  • On Linux, Sesame Link also stops when you log out. To keep it running, run loginctl enable-linger, or sudo loginctl enable-linger $USER if that’s refused.

Claude Code or Codex is signed out

Section titled “Claude Code or Codex is signed out”

When Claude Code or Codex is signed out on a computer, your clients can’t start its sessions there. Sign in again on that computer; sessions that are already running keep going.

Terminal window
claude /login    # Claude Code
codex login      # Codex

Pi is unavailable or cannot start

Section titled “Pi is unavailable or cannot start”

Run pi --version and tmux -V in your terminal. Pi needs its supported Node version and tmux 3.4 or newer. Start pi and run /login to authenticate a provider, then send a message there to check that it works. Run sesame-link restart after installing or updating Pi, then sesame-link status to see what the computer can start. See Pi setup.

Your login was used elsewhere

Section titled “Your login was used elsewhere”

Sesame Link signed out this computer’s saved login because a copy of it was used somewhere else. This happens when this computer’s files are copied to another computer, for example a home folder restored from a backup or synced elsewhere. Run sesame-link auth login to sign in again. If you can’t explain the copy, check who else can use this computer.

A new session won’t start

Section titled “A new session won’t start”

The error your client or terminal shows says why. A computer refuses a new session when:

  • It is at its session limit: 8 sessions by default. End a session, or start Sesame Link with a higher --max-sessions. See Limits.
  • It is low on memory: it needs at least 1 GiB free.
  • Claude Code or Codex is signed out: see Claude Code or Codex is signed out.
  • Sessions can’t read the folder: on macOS, see the next section.
  • Claude Code or tmux isn’t installed, or Sesame Link can’t find it: install it, check that it runs in a new terminal window, then run sesame-link restart.

Sessions can’t open protected folders

Section titled “Sessions can’t open protected folders”

On macOS, sessions borrow one app’s permission to open protected folders such as Documents, Desktop, and Downloads, the same way a command uses its terminal’s permission. If Sesame Link starts when you log in, that app is Terminal, which is why a Terminal window flashes open at login. If you started Sesame Link yourself, it’s the app you started it from. If you started it over SSH or from a background job, there’s no app to ask, so sessions can’t open those folders and macOS won’t prompt you.

To see which app your sessions use, run sesame-link status --verbose and look at Folder access. Then:

  1. Allow that app under System Settings > Privacy & Security > Files & Folders, or add it under Full Disk Access.
  2. End every session and run sesame-link restart (from that terminal, if it’s a terminal).

Sessions can’t find your tools

Section titled “Sessions can’t find your tools”

Sessions use the PATH your login shell sets up. New Claude Code sessions pick up changes to it. Codex reads it only when it starts, so restart it, which ends any Codex turns in progress:

Terminal window
sesame-link restart --restart-codex

If your shell takes more than five seconds to start, sessions use the PATH Sesame Link started with instead. Speeding up your shell’s startup fixes that.

A prompt moved to the terminal

Section titled “A prompt moved to the terminal”

If no client is watching, a permission prompt waits three minutes, then moves to the terminal. It also moves there when Sesame Link stops. Answer it at the computer, or attach to the session with sesame-link sessions attach <id-or-name>.

Get help

Section titled “Get help”

Send a diagnostics bundle

Section titled “Send a diagnostics bundle”

Collect one archive of logs, status, and session state to send to Sesame support:

Terminal window
sesame-link diagnostics

The archive is written to the current folder. It leaves out secrets but can include conversation text, so look it over before you send it, and never attach it to a public issue.

Report a problem

Section titled “Report a problem”

In the web app, choose Report a problem from the menu, or from a session’s ••• menu to report about that session. Describe what happened and send it. The report goes privately to the Sesame team. It includes your Sesame account and email, your browser and computers, the versions of Sesame Link and your coding tool, and the session’s identifiers. Tick Include transcript to also send the session’s conversation as the page shows it, tool output included. The transcript is never sent unless you tick the box.

To request a feature, or to discuss a problem in public, use the Sesame Link issue tracker on GitHub. Search existing issues first. Include the output of sesame-link --version and sesame-link status, and the version of your coding tool, such as claude --version. Issues are public, so don’t paste raw logs or session content.

Report security problems privately through GitHub’s vulnerability reporting, never in a public issue.

Error reports

Section titled “Error reports”

Sesame Link sends crash and error reports to Sesame. Reports never include messages, file paths, or session content. To stop sending them:

Terminal window
sesame-link config error-reporting off

Contact support

Section titled “Contact support”

For anything you’d rather not post publicly, email raven@sesame.com or message @DarkMirage on X.