Reference

Troubleshooting

Find the message or symptom below, then check the profile and agent it applies to before repeating setup.

Install and setup

The terminal says "sleeptalk: command not found."

For the PyPI quickstart, activate the environment in each new terminal:

Terminal

. ~/.venvs/sleeptalk/bin/activate
sleeptalk

If you used the release installer, open a new terminal after installation. If it printed "Add this directory to your PATH", add that directory, or use the full command path it printed.

Setup ignores the profiles in my repository.

Sleeptalk uses a repository's config/profiles/ only after you trust it. Run sleeptalk trust inside the repository. Until then it uses your default home, ~/.sleeptalk. The working directory's .env is never read.

My agent is listed, but it will not connect.

Found on PATH does not mean logged in. Log the agent in to its model on the same machine, then retry. Follow the install or login hint setup prints, and see the agent's page: pi, Hermes, Claude Code, Codex, Cursor, OpenClaw, or oh-my-pi.

A setup probe says "Select permission behavior that retains approval prompts."

Setup probes refuse auto, skip, and never. Set permission_mode = "pending" (or deny) in the profile's [agent] section, then rerun setup.

Python reports "No module named venv", "ensurepip is not available", or "externally-managed-environment".

Use Python 3.11 or newer and install into a virtual environment, as in the Quickstart. On Ubuntu, install python3-venv if needed. The release bundle installer can supply Python and an isolated environment instead. Keep optional extras in that same environment.

Keys

My key is rejected.

The settings page names the reason:

Message	What to do
The service rejected this key.	Copy a current key from the provider's dashboard.
This key lacks the permissions voice needs.	Create a key with full access.
That voice isn't available on this account.	Pick another voice, or check the provider account.
This account is out of credit or rate limited.	Add credit, or wait and retry.
The check took too long.	Retry.
The credential store is locked.	Your store uses the Keychain or Secret Service. Unlock it, then retry.
That key isn't on this machine any more.	Enter the key again. After restoring a Mac from Time Machine, the file store is not in the backup, so enter each key again.
That service or model can't be set up here.	Choose another provider or model.

Replace a key with sleeptalk settings --open, or ask your agent for a new private settings link. Never paste a key into a chat or an issue.

Browser calls

The browser opens, but I cannot hear a reply.

Allow microphone access and check the browser's audio devices. Confirm that Sleeptalk is still running and the agent can answer. A local link only works on the machine that printed it; use a hosted or tailnet link from your phone.

A hosted call ended after 30 minutes.

Calls through the hosted relay are limited to 30 minutes, announced before the call ends. Start a new call, or use a tailnet or local call, which have no time limit. See web calls.

A tailnet call refuses to start.

Tailnet calls need Tailscale on the host with HTTPS certificates enabled, because browsers only allow the microphone over HTTPS. The receipt names the problem:

Code	Fix
`tailscale_missing`	Install Tailscale and sign in.
`tailscale_not_running`	Run `tailscale up`.
`tailscale_https_disabled`	Enable HTTPS certificates under DNS in the Tailscale admin console, once.
`tailscale_operator_required`	Run `sudo tailscale set --operator=$USER`.
`tailscale_serve_failed`	Check `tailscale serve status` on the host.

The hosted relay is never used as a silent fallback.

Advanced settings from a call says "No browser on the computer running your agent."

Advanced settings normally offers an Open settings link for your phone. This message means the host couldn't reach the hosted service, so it tried its own browser, and it has none, such as a VPS. Run sleeptalk settings in a terminal on that machine, or ask your agent for a link with sleeptalk host settings-link.

Speech

Local speech does not understand my language.

The bundled local models are English only. For other languages, choose a cloud speech provider. See languages.

Discord

The bot will not start: "Discord authorization requires a guild, allowed_channel_ids, and operator_ids."

Discord bots are closed by default. Lock the bot to your voice channel and your Discord account in sleeptalk settings --open, or set allowed_channel_ids and operator_ids in the profile. To let anyone in the server talk to the agent, set authorization_required = false.

Doctor says Discord refused the bot's intents (close 4014).

Voice needs no privileged intent. The profile enables text summons or rooms, which read Message Content. Enable Message Content under Bot, Privileged Gateway Intents, in the Discord Developer Portal, or turn that feature off. Then rerun sleeptalk doctor.

"Could not sync slash commands (Missing Access)."

The bot was invited without the applications.commands scope. Re-invite it with that scope so its slash commands work.

The bot joins but does not hear me.

Your Discord user ID is not in operator_ids or speaker_ids, or the channel is not in allowed_channel_ids.

Opus errors on start.

Install libopus (brew install opus or sudo apt install libopus0), or set opus_library in the profile.

Profiles and calls

How do I check a profile?

Run the doctor with the profile path. --offline skips the network checks.

Replace the example profile path

sleeptalk doctor --config /path/to/profile.toml

How do I stop a call?

Press Ctrl+C for a call attached to your terminal. For a call started through sleeptalk host, run sleeptalk host list, then sleeptalk host stop <callId> with the returned ID.

More recovery guides

Use call lifecycle and recovery for lost start responses, profiles and credentials for binding or key problems, and deployment for services.