FAQ & troubleshooting
Answers to the questions new users ask most, from API keys and costs to backups, logs, and bots that don't reply.
Getting started
I don't have an API key. Can I still use Suzent?
Yes. Ollama runs models on your own computer with no key and no internet connection. Google Gemini has a free tier, and the ChatGPT subscription provider signs in with your ChatGPT account instead of a key.
The terminal says "command not found: suzent".
Close and reopen your terminal after installing. If it still fails, check the
setup script's output for how to add Suzent to your PATH. See the
Quickstart.
Suzent won't start because the port is in use.
Suzent uses port 25314. If an older Suzent is still running, suzent stop
ends it. Otherwise start Suzent on another port with suzent start --port <port>,
or set SUZENT_PORT. See Command line.
How much am I spending?
Open Settings → Usage to see your spending, API calls, and tokens per day.
Type /status in a conversation to see that conversation's tokens and cost.
Your data
Where are my files?
Everything is in the .suzent folder in your home folder. Files the agent
keeps go to the project's library, in ~/.suzent/sandbox/projects/<project>/.
See The data folder for the full layout.
Is my data sent anywhere?
Suzent runs on your computer and doesn't send usage analytics. Your messages go to the model provider you choose, and with Ollama nothing leaves your machine. Web searches go to DuckDuckGo, or to your own SearXNG. Suzent also checks GitHub for new releases. GitHub Sync and chat apps only send data once you set them up.
Can I use the phone app away from home without Tailscale?
Yes. Deploy your own relay, for free on Cloudflare Workers or with Docker on any server, and add it under Settings → Devices → Relay. Suzent has no hosted relay, and phone traffic through yours is end-to-end encrypted. See Your own relay.
How do I back up Suzent, or move to a new computer?
Turn on GitHub Sync. It keeps your settings, skills, and memory in a private GitHub repository you own, and brings them to another computer. API keys are never synced, so add them again in Settings → Providers on the new computer.
Your conversations are not synced. Each one is a plain-text file in
~/.suzent/chats/, so copying that folder keeps all of them. Quit Suzent first
so no conversation is half-written. Put the folder back in a new ~/.suzent
and Suzent rebuilds your conversations from it on its next start; they appear
in your Home project, because projects themselves are kept in chats.db.
How do I start over from scratch?
To empty a single conversation, type /clear. To reset Suzent entirely, quit
it, run suzent service stop if you use the background service, then rename
or move the ~/.suzent folder. Suzent creates a new, empty one the next time
it starts. Your API keys stay in your system's keychain and are picked up again.
The agent forgot something, or remembers something wrong.
To forget something, delete it in the Memory panel. To correct it, say the corrected version in a conversation. Memory is also a set of Markdown files you can edit yourself. See Managing what's remembered.
Using the agent
The agent can't see my folder.
The agent only reaches its project library, the shared folder, and folders you mount. Click Working Dir in the chat box and choose the folder. See Giving the agent access to your folders.
How do I undo what the agent just did?
To undo its file changes, use Git (for example git restore . in the folder)
or ask the agent to revert them; Suzent doesn't roll files back. To have it try
again, click the retry icon under its last reply, or type /retry: that rewinds
the conversation to before the last turn and runs your message again. See
Slash commands.
Can I stop the agent asking for permission all the time?
Switch the conversation to Smart or Full Access with the mode selector next to the message box, or choose one of the "always allow" answers when it asks. See Permissions & approvals.
Scheduled tasks don't run when I close the window.
Tasks, heartbeats, and chat apps only work while Suzent is running. On Windows and macOS, choose Minimize to tray when you close the window (or set it under Settings → Background Service → When you close the window) and Suzent stays in the notification area or the menu bar, so tasks keep running until you choose Quit. After you quit, or on Linux, turn on Settings → Background Service. See Automation.
Troubleshooting
My chat app bot doesn't reply.
Check three things. Suzent must be running, so turn on the background service if you quit. The app must be enabled in Settings → Social Channels. And your own user ID must be in Allowed users on the Access control tab, because messages from anyone else are refused. See Access control & pairing.
The agent can't see my desktop apps.
Desktop control is a separate plugin, and it is off until you install it.
Turn on the Desktop plugin, then confirm Install agent-desktop on its
card (or run suzent plugin install desktop). Suzent downloads the pinned
1.0.2 release only after that confirmation, checks it against the hash the
plugin carries, and on a Mac opens the Accessibility guide. It does not download anything when the agent merely
tries to use the tool. You can still install the program yourself or set
SUZENT_AGENT_DESKTOP_BIN. The Docker sandbox has no screen, so desktop
actions always run on the computer itself. See
Desktop apps.
The sandbox won't start.
The sandbox needs Docker. Make sure Docker Desktop (or Docker Engine on Linux)
is running, and that docker ps works in a terminal. To work without it, turn
the sandbox off in Settings → Security. See
Using the sandbox.
A reply stopped with "The model provider stopped responding".
When a model request times out, the connection drops, or the provider is busy or limiting requests, Suzent waits a few seconds and sends it again, up to three times. Each retry shows as a line in the reply, and tool work the agent already finished is not redone. This message means all three failed. Check your network, proxy or VPN, then press Retry. A rejected API key, an empty balance, or a conversation too long for the model is not retried; the message says which it was. You can also switch the chat to another model and resend.
Where are the logs?
Run suzent logs --desktop for the desktop app's log, and add -f to follow
it live. If you use the background service, its log is under
Settings → Background Service → Service log, and suzent service logs
prints where the file is. All logs are kept in ~/.suzent/runtime/.
Something seems broken after installing.
Run suzent doctor to check that the tools Suzent needs are installed. For a
background service that won't start, run suzent service doctor.
How do I update?
Open Settings → About and click Check now under Software updates, or run
suzent update. If an update was interrupted, run suzent repair. See
Updating Suzent.