Configure
Profiles and credentials
Find where your profiles live, how keys are stored, and how to replace a key without ever seeing its value.
Find the active configuration
--config PATH selects a profile file directly. Otherwise Sleeptalk resolves a state directory in this order:
$SLEEPTALK_HOME, if set. There is no--homeflag.- A repository you trusted with
sleeptalk trust, found from the current directory. Its profiles live inconfig/profiles/. ~/.sleeptalk.
sleeptalk doctor --config /path/to/profile.toml --offlineDoctor's first line says which state directory it used and why. Offline checks skip provider connectivity.
The effective configuration combines defaults, the root sleeptalk.toml, and the profile. Tables merge field by field; lists and single values replace the earlier value. A profile holds only its overrides.
Trust a repository's config
A repository can keep its own config/profiles/. Those profiles choose the agent command, provider endpoints, and the .env that feeds the agent, so Sleeptalk never uses a cloned repository's config on sight.
Sleeptalk looks for a repository from the current directory upward, at most three levels and never past your home directory. It looks for config/profiles/*.toml, or a pyproject.toml that declares the sleeptalk entry point. If the repository isn't trusted, Sleeptalk names it, skips it, and uses ~/.sleeptalk.
sleeptalk trust
sleeptalk trust --removesleeptalk trust also takes a path. The trust list is ~/.sleeptalk/trusted-repos, and it counts only when your user owns it and nobody else can write to it.
Where things live
| Data | Location |
|---|---|
| Profiles | profiles/<slug>.toml under the state directory, or config/profiles/<slug>.toml in a trusted repository |
| Shared defaults | sleeptalk.toml under the state directory |
| Agent environment | .env under the state directory |
| Logs | logs/ under the state directory, private to your user |
| Keys and tokens | The private store: ~/.local/share/sleeptalk/credentials by default, or the macOS Keychain or Linux Secret Service with sleeptalk[credentials] |
| Verified agent runtimes | ~/.local/share/sleeptalk/runtimes |
| Local speech models | ~/.cache/sleeptalk/models; see local speech |
Changing SLEEPTALK_HOME does not isolate the credential store, agent installations, or OS logins. For a clean trial, use a separate user account or machine.
How keys are stored
Every key you enter is checked once with the provider that issued it, then written to the private store on the host. The check transcribes a short clip and speaks one line, which uses a little credit. The host is the machine running Sleeptalk. Keys that fail the check are not kept.
By default the store is ~/.local/share/sleeptalk/credentials, a directory only your user can open, holding a SQLite file only your user can read (0600). Nothing encrypts that file beyond the operating system's permissions, so any program running as your user can read it. Your agent already has the same access. On a Mac the folder is excluded from Time Machine, so backups don't carry plaintext keys. After restoring onto a new machine, enter your keys again.
To keep values in the macOS Keychain or the Linux Secret Service instead, install sleeptalk[credentials] before the first key is saved. A file store can move there later with Move keys on the settings page's Keys page, or sleeptalk host credentials move-to-keychain; that needs a desktop session. Calls then need you logged in, and macOS may ask once to allow access after Python is upgraded, which a call started from your phone can't answer. That is why the file is the default. The Keys page says which store is in use.
A profile names each store entry and never holds the key, so profiles are safe to read, copy, and show to an agent:
[credentials.refs]
OPENROUTER_API_KEY = "credential:…"The settings page (including an agent's key request), the terminal wizard, and sleeptalk host ensure all keep speech keys, realtime keys, and the Discord bot token in the store. Terminal setup removes any older plain-text copy from .env. Tokens for a Hermes dashboard, OpenClaw, or your own agent (its token_env) go to the store too, referenced from the profile. An older copy in .env still works, and moves to the store the next time you save that profile's agent.
To pass a key to sleeptalk init without it showing in ps or your shell history, give the flag -, for example --speech-key -. It asks at a hidden prompt, or reads the key from stdin when piped.
Sleeptalk reads .env from the profile's own directory, from the project root for a project-layout profile, and from $SLEEPTALK_HOME. It never reads the working directory's .env, so the repository you happen to run in can't fill the agent's environment.
Sleeptalk never writes a key to a log, a receipt, a transcript, or a chat message. See credentials and data handling and where your keys live.
Workspace and host binding
New bound profiles record the host, OS user, workspace identity, and agent configuration. Startup checks those bindings. Moving the directory, using another worktree, or changing the adapter can require a new profile.
A folder with the same name on another machine is not the same workspace. Keep the existing profile and create a separate one for the new setup. Don't delete binding fields to get past a mismatch.
Replace a speech key
On the settings page, open Speech service, select the service in use, and choose Replace next to the saved key. The new key is checked, stored, and replaces the old one; your models and voice stay.
An agent replaces a key through the private page instead:
sleeptalk host credentials status credential:REFERENCEStatus returns metadata and affected-profile identifiers, never the key value. Then run sleeptalk host input link with --replace-reference and one --affected-profile for every profile reported. You confirm the replacement on the page.
The key is validated before the reference switches. The old key is then removed from the store unless another profile still uses it. Running calls may keep the old key until they restart. Check each affected profile and its voice afterward. Model credentials use the separate model entry flow.
Removal and retained data
Deleting a profile removes the keys no other profile uses. The settings page's Keys page lists every stored key with the profiles using it, and Remove unused keys clears the rest. In a terminal:
sleeptalk host credentials list
sleeptalk host credentials prune --confirm-local-deletionA key counts as used when a profile in ~/.sleeptalk/profiles, $SLEEPTALK_HOME, or a trusted repo names it. A profile kept somewhere else and started with --config isn't seen, so don't prune if you rely on one.
sleeptalk host credentials remove requires --confirm-local-deletion and an --affected-profile for every profile that uses the key. Deleting a key from Sleeptalk does not revoke it at the provider; do that in the provider's dashboard. Deleting profiles does not remove runtime installations.
Stop the call or service that uses a profile before removing its files. Check shared references first. If you think a key has leaked, rotate it at the provider first.