Help

Troubleshooting and FAQ

Fixes for the problems people meet most: pairing, sign-in, harnesses, the runner, desktop updates, the network and paused features.

Last updated November 15, 2026View as Markdown

Find the message you see, then follow its fix. If none fits, write to [email protected].

Sign-in and pairing

The desktop app's sign-in code fails

The desktop app signs you in through your browser: it opens Sign in a device with a code to approve.

  • This code is unknown or has expired: the code lived too long. Start sign-in again from the desktop app and approve the new code straight away.
  • This code was already used: the device is signed in, or another tab approved it. Go back to the desktop app.

If the browser page never opens, check that your network allows EasyCode's hosts: Network and firewall.

The local app says "Open EasyCode from your terminal"

The local app runs commands and edits files as you, so it opens only in a browser you paired with it. Start it from a terminal; it opens the pairing link for you:

easycode dev

That pairing link is not valid for this machine means the link is old or from another launch. Each launch makes a new one. Use the link the latest launch printed. Settings → Access & pairing lists the browsers that can use the app.

Harnesses

Settings → Harnesses shows each harness's state as a badge.

Not installed

The app didn't find the harness's command. Click Install to run its install command in a terminal below, or install it yourself. Each harness's command is in the harness reference.

Desktop app only

When you start the desktop app from the Dock or the Start menu, it reads your PATH from your login shell, so tools installed with Homebrew, nvm or volta are found. If you install a harness while the app is open, quit and reopen it. Settings → Desktop shows how this launch found your PATH.

Signed out or Expired

The harness is installed but has no valid login. Click Connect; it runs the harness's own sign-in command in a terminal, and you sign in with the vendor. EasyCode never sees the login. An Expired badge may say when it checks again.

Needs update

The installed version is older than the version EasyCode needs. Click Update.

The runner

The runner is not answering

The runner is the local process that drives your harnesses. When it is down, harness cards show Runner down and sessions can't start.

The desktop app restarts a runner that stops on its own a few times. If it stays down, quit EasyCode and open it again. Settings → Diagnostics shows what the runner counted.

Desktop updates

Settings → Desktop shows the update state. Check for updates asks now; Retry follows an error.

  • Restart to update waits while sessions are running, then installs once they finish.
  • A required update: when your org needs a newer version, the update banner says so. Install it; an older version stops working with your org once the requirement starts.
  • Your system has no keyring, so your sign-in is stored with weak protection: this Linux desktop has no keyring service, so the app can't use the OS's secure storage. Run it on a desktop with a keyring service for full protection.

Unsigned builds

Pilot builds may be unsigned, marked Unsigned alpha or Unsigned beta on the download page. Updates then install by hand, and the app guides you:

The app downloads the update, checks it, and opens the disk image. Drag EasyCode to Applications and replace the old one, then open it again.

More in Desktop app.

Network

Sign-in, sync, updates or the studio fail behind a company firewall or proxy? Your network must allow EasyCode's hosts. Network and firewall lists them.

Something is off or paused

Some messages mean a part of EasyCode is turned off for your org, not that something broke.

  • Knowledge is off for your org, The library is off for your org, Board isn't enabled for your org, or a rail item missing: that module is off for your org. Ask an org admin; if you are the admin, ask your EasyCode contact to turn the module on.
  • Pick-up is paused by EasyCode, The Board is paused, This is switched off for now, Knowledge runs are switched off for now, publishing is switched off for this org: a kill switch is off for now. It isn't something you can fix; work resumes when it is back on.

Kill switches and modules lists each one and what it pauses.

FAQ

Why can't I read a teammate's session?

You see a teammate's session title and status when you can see its product. To read its content or pick it up, all of these must hold: it isn't Private, your org has session content on, you are a contributor or maintainer on its product, and you can read its repo on GitHub. A session with no product is its owner's alone. Roles and access.

Can I start a session from the web app?

No. The web app runs no harness. Start sessions from the desktop app, and follow them from either.

Does EasyCode store my harness login?

No. Each harness signs in on your machine and keeps its own credentials. EasyCode never reads them. Security and privacy.

Does my code train a model?

EasyCode trains no models. Your harness vendor's terms apply to what you send them.

Which harnesses work?

Claude Code, Codex, Cursor, Copilot, Gemini, OpenCode and pi. See the harness reference for support levels and tested versions.

Something wrong or missing? Suggest a change

On this page