Troubleshoot your setup

I installed the app, but Tutor local cannot be found

Tutor ACP is the desktop app; Tutor MCP is the learning server. For a personal setup, install the server as well, then set its full executable path in Settings → Institution → Tutor program.

Check the binary in a terminal with tutor-mcp --version, or use its complete path. If it works in a terminal but not in the app, restart the app after installation or keep the full path in its settings.

A native Windows agent needs a Windows executable. A WSL2 agent needs the Linux executable in the selected distribution. Set Program arguments to the JSON array ["--local"], then select Verify local Tutor.

For an institution, the organisation runs the server. Follow the app connection guide with its HTTPS address.

The agent is installed but asks me to sign in

Bundled agents provide the compatible software runtime. Your provider account or API access is still required. In Settings → Agents, select Codex or Claude, connect it and complete the authentication method it offers.

The provider account is separate from your Tutor identity and institution membership. Provider limits or costs are governed by that provider. Some advanced provider features also have their own system requirements; the client runtime guide documents the delivered setup.

For a manual WSL2 setup, check that the adapter and provider sign-in exist for the same Linux user in that distribution. Windows and WSL do not automatically share provider credentials.

I cannot connect to my institution

1. Check the exact HTTPS origin provided by your institution. In Tutor ACP, use the origin without /mcp.
2. Select Verify institution and check the displayed name and origin.
3. Open your account and confirm that the identity is marked Backed up.
4. Ask the institution administrator to confirm that your current active and recovery public npub values are authorised and your membership is active.
5. Try Connect with my account again.

A remote hobby MCP client uses an endpoint ending in /mcp and its account’s OAuth sign-in. A native institution uses the app’s signed-identity connection. Choose the journey that matches the service you were given.

If you changed computer or restored an account, use the encrypted identity backup described in backups and updates. Generating a fresh identity creates different public keys and does not restore the previous account.

The remote service is unreachable

Operators can check the public readiness endpoint:

curl --fail https://tutor.example.org/ready

Check DNS, inbound ports 80/443, the HTTPS certificate and the reverse proxy. An AAAA record should exist only when the service is reachable over IPv6. Keep the application port private and preserve the public Host header through the proxy.

For an institution, also check that the migrator finished successfully, runtime database grants are current and the API can access PostgreSQL with its configured CA. Follow the institution deployment checklist and the server’s operational logs.

Fix the certificate or trust configuration at its source. The normal setup verifies HTTPS certificates.

A course or publishing action is missing

Check the selected account, institution and active course. A different local profile or remote service has a separate learning history. The app does not automatically move courses between profiles.

Courses appear according to their audience, invitations, membership and enrolment policy. Ask the owner to confirm your access. Institution roles and the agent’s delegated permissions are separate: allowing a tool does not make a learner an administrator.

If a course is shared through owner review, submit the changes for review and wait for publication. A newly published version does not silently replace the version already used by enrolled learners. See sharing and contribution review.

Some institutions restrict personal programmes. Their catalogue and policy determine which learning routes are available.

My message is marked Ready to send or a reply was interrupted

Ready to send means the app has kept your message while a required connection is incomplete. Finish the agent and Tutor setup in the same window; the app resumes the message once the connections are ready.

An interrupted response remains identified as interrupted. Review what was actually saved before continuing. You can return to the same conversation and ask to resume its current course.

If a tool permission is requested, review the requested operation. Saved tool choices can be changed under Settings → Agents and remain tied to the selected account, institution and agent.

Installation is blocked or data is missing after an update

On Windows, follow your organisation’s software and PowerShell policies. If the server script cannot run, use the matching release ZIP, verify its checksum and set the full executable path. Download the desktop installer from the project’s official release.

Before changing versions, save your identity backup and learning data. If existing local data cannot be opened because its installation key is missing, restore the original database and key together. Creating a replacement key does not recover encrypted data.

For an institution upgrade, the migrator and database grants must match the new server before API and worker startup. See backups and updates.

When asking for help in GitHub issues, include your operating system, Tutor app and server versions, the failing step and a redacted error. Keep private keys, backups, passphrases, tokens and personal learning content out of the report.

Keep going.