Troubleshooting

slycode doctor

Doctor runs nine checks: Node version, build tools, workspace, config, .env, port availability, global CLIs, installed AI coding agents (claude, codex, gemini), and workspace structure. Run it first and fix what it flags; the sections below cover what the findings mean.

Services will not start

slycode start checks ports, spawns the services, and waits up to 15 seconds for each one to report healthy. If SlyCode is registered as a system service (systemd, launchd, or Task Scheduler), start and restart delegate to the service manager, so use slycode restart rather than killing processes by hand. If startup still fails, run slycode doctor and work through the failing checks.

Port conflicts

SlyCode uses three ports: web (7591), bridge (7592), and messaging (7593) by default. The doctor port check can tell SlyCode's own services apart from foreign processes:

• A SlyCode service holds the port: SlyCode is already running. Use slycode restart instead of starting a second copy.
• A foreign process holds the port: stop that process, or move SlyCode to different ports with slycode config.

Missing build tools warning

Prebuilt native binaries ship for macOS, Windows, and Linux (arm64 and x64), so most installs need no build tools. On platforms without a prebuild, the installer warns that the C/C++ toolchain is missing and prints the right install command for your package manager. The warning never blocks the install; run the printed command and reinstall.

Forgot your password

slycode reset-password

This clears the dashboard password and signs out all sessions; the next visit shows the first-run password screen again. It is a local-only escape hatch that needs no network access, so you can never be permanently locked out. Because it signs out every session, expect to log in again everywhere.

Dashboard unreachable from another machine

By default the web service binds 127.0.0.1, so the dashboard is local-only out of the box. This is intentional. Exposing it to other devices is an explicit opt-in: choose it in the setup wizard, or flip it later:

slycode config host 0.0.0.0

The mandatory dashboard password is what makes exposure safe, but HTTPS is still strongly encouraged when serving beyond localhost: use tailscale serve or a reverse proxy. SlyCode does not provision certificates itself. The bridge and messaging services always bind to localhost regardless of this setting, since neither has its own auth.

Red warning banner in the dashboard

A red banner appears when the UI is served over plain HTTP from a non-loopback host, recommending HTTPS via tailscale serve or a reverse proxy. Loopback HTTP and any HTTPS setup are silent. The banner means your login cookie and traffic cross the network unencrypted; put HTTPS in front of the dashboard to clear it.

Session did not resume

Each provider has its own resume mechanism: Claude and Gemini use a --resume flag, Codex uses a resume subcommand. SlyCode detects the provider session ID automatically and uses the right one, so a failed resume usually means the underlying CLI session exited. Check the exit output captured on the card: stopped sessions keep their last lines of terminal output and exit code, which normally show why the provider exited.

Prompt did not land in a session

Prompt delivery into a running session is verified: SlyCode confirms the prompt was queued in the provider's input box, submits it, and confirms the input box cleared. Failures are surfaced instead of silently dropped. A blocked result means a dialog (trust prompt, update prompt, login) is sitting over the input box; open the terminal, clear the dialog, and retry. A busy session rejects the prompt rather than interleaving it with running output; retry when the session goes idle.

Provider CLI not found

SlyCode orchestrates the provider CLIs; it does not install them. Claude Code, Codex CLI, and Gemini CLI must each be installed and authenticated separately before sessions can start. slycode doctor reports which agents it can find. See Multi-provider setup for details.

Bot not responding

The messaging service only runs when a channel token is present in .env. If you added Telegram after install, check that the bot token and your user id are both set, then restart SlyCode. The bot answers a single authorized user: messages from any other account are ignored, so make sure the user id matches the account you are messaging from.

Voice messages not transcribing

Speech-to-text needs a configured backend, selected via the STT_BACKEND variable in .env. If voice notes arrive but nothing happens, that backend's keys or paths are the first thing to check:

• openai: Whisper API, needs OPENAI_API_KEY.
• local: whisper.cpp, needs WHISPER_CLI_PATH and WHISPER_MODEL_PATH.
• aws-transcribe: AWS Transcribe via S3, needs AWS_TRANSCRIBE_S3_BUCKET and uses the instance IAM role, no API key.

See Messaging and voice for full setup.

slycode update installs the latest release, refreshes skills, actions, and provider configs, reinstalls system services, and then verifies that each enabled service comes back up on its port. If a service fails to return, the update prints the log locations to check, so a broken update tells you where to look.

If skills or actions look stale but you do not want a package update, slycode sync refreshes skills, actions, and provider templates in place. It preserves your provider defaults while merging in template changes.

If none of this covers your problem, reach out through the contact link on the homepage, or open an issue on the SlyCode GitHub repository. Including your slycode doctor output makes most problems much faster to diagnose.