Credentials and data

Where your keys are stored, which pages can take them, and which services see a call.

Sleeptalk is software you run, not a service you sign up for. There is no Sleeptalk account, and no Sleeptalk server receives a key.

What happens to a key you enter

1. Checked with its provider. Sleeptalk sends the key only to the provider that issued it, to prove it can listen and speak. It transcribes a short clip and speaks one line, which uses a little credit. A key that fails is not kept.
2. Written to a private store on the host. The host is the machine running Sleeptalk. By default the store is ~/.local/share/sleeptalk/credentials, a directory and SQLite file readable only by your user. Nothing encrypts that file beyond the operating system's permissions. On a Mac the folder is excluded from Time Machine, so backups don't carry plaintext keys; after restoring onto a new machine you enter them again. If you install sleeptalk[credentials] before the first key is saved, the store keeps values in the macOS Keychain or the Linux Secret Service instead. A file store can move there later; see move keys to the Keychain. The settings page's Keys page says which store yours uses.
3. Referenced from the profile. A profile names the store entry, never the key, so profiles are safe to read, copy, and show to an agent.
4. Used at call time. The running call reads the key from the store and sends it to its provider. It goes nowhere else.

Sleeptalk never writes a key to a log, a receipt, a transcript, or a chat message. Receipts for agents name where a key came from, never its value. Anyone who can run programs as your user can read the file store; that is the same trust your agent already has.

Move keys to the Keychain

An existing file store can move into the macOS Keychain or the Linux Secret Service. Use Move keys on the settings page's Keys page, or run:

sleeptalk host credentials move-to-keychain

It needs sleeptalk[credentials] and a desktop session. The trade-off: calls then need you logged in to that computer, and macOS may ask once to allow access after Python is upgraded. A call started from your phone can't answer that prompt. That is why the file is the default.

Keys only travel encrypted

A custom base_url for a speech provider must use https://. Plain http:// is accepted only on 127.0.0.1 or localhost. Agent gateways (Hermes, OpenClaw) need wss:// or https:// too, unless they are on this machine or on your tailnet (100.64.0.0/10 or a *.ts.net name). No key or token crosses a network unencrypted.

Where you can enter a key

When an agent sets Sleeptalk up for you, it sends you a private link with sleeptalk host input link. It opens the settings page on just that request. The agent never sees the key, and must never ask for one in chat.

Tokens for a Hermes dashboard, OpenClaw, or your own agent go to the same private store, and the profile references them. An older copy in .env still works, and moves to the store the next time you save that profile's agent.

Keys Sleeptalk can reuse

If a speech-capable key (OpenRouter, Venice, Groq, or Together) is already on the host, setup can reuse it, but only when you say so.

• sleeptalk host ensure names what it found and where, and your agent asks you first.
• The settings page looks only after you click Look on this computer. It remembers that choice until you click Stop looking.
• The terminal wizard offers a found key first. Nothing to paste; a copy goes into Sleeptalk's store.

It looks in Sleeptalk's own model profiles, the environment, Hermes's ~/.hermes/.env and config.yaml, OpenClaw's ~/.openclaw/.env and openclaw.json, and pi's or oh-my-pi's auth.json and models.json. It reads only files your user owns. Looking notes where a key is, never its value.

Once you choose a key, it is proved with the provider, then copied into the store. The original stays where it was, so rotating it there does not update Sleeptalk's copy. The key never passes through the agent's chat.

A project's .env is never a source, because a cloned repository could plant a key there. Dotenv files are read literally, and a key given as a shell command is never run.

Subscription logins (Claude, ChatGPT, Cursor) are never used. They belong to the vendor's own app. Sleeptalk takes API keys only.

Replace and remove keys

When you replace a key, Sleeptalk removes the old one from its store unless another profile still uses it. Deleting a profile removes the keys no other profile uses. Neither revokes a key at the provider.

The settings page's Keys page lists every stored key with the profiles using it. Remove unused keys clears the rest. In a terminal:

sleeptalk host credentials list
sleeptalk host credentials prune --confirm-local-deletion

list shows references, providers, and the profiles using each key, never a value. A key counts as used when a profile in ~/.sleeptalk/profiles, $SLEEPTALK_HOME, or a repo you trusted with sleeptalk trust names it. A profile kept somewhere else and started with --config isn't seen, so don't prune if you rely on one.

Repositories you open

Sleeptalk reads a repository's config/profiles/ only after you run sleeptalk trust in it, and never reads the working directory's .env. A cloned project cannot choose your agent command, speech endpoint, or agent environment. sleeptalk trust --remove stops trusting a repo.

What each service sees

• Your speech provider receives the audio or text it transcribes or speaks.
• Your agent and its model provider receive your request and any workspace context the agent uses.
• For hosted browser calls, the hosted relay handles signaling. It issues TURN credentials only after a browser redeems the call link, within daily budgets and rate limits.
• Call audio travels between the browser and your host under DTLS. Transcripts and agent state use a WebRTC data channel, end to end, never through the relay.
• Tailnet and local calls load their pages from your own host and do not use the hosted service.

The hosted service also serves the call page and the phone settings page. Their end-to-end protections hold while it serves the code in the public repository; this limit is stated in SECURITY.md.

Discord bots

A Discord profile without operator_ids and allowed_channel_ids does not start unless it sets authorization_required = false. An open bot warns at startup, never pings anyone, and takes commands only in a server. See Discord.

Logs and diagnostic reports

Call logs, speech scratch files, and debug probes are private to your user, and so is the logs folder. Every log line is masked for anything shaped like a secret before it reaches the console or the log file: token= in a URL, Authorization and Bearer values, Discord bot tokens, and sk- style keys. Tracebacks are masked too. Logs can still contain operational details, so do not assume a log is anonymous. Deleting a profile does not remove every trace.

Before sharing a report, remove conversation text, paths, keys, and call or setup links. Include the command, the visible symptom, and the Sleeptalk version.

Billing

Speech usage is billed to your provider account. Agent subscriptions and model API usage are separate. Setup checks can use provider credit. Removing a key from Sleeptalk does not revoke it; do that in the provider's dashboard.

Report a security issue

Report vulnerabilities privately through GitHub private vulnerability reporting. Do not open a public issue. The full details are in Where your keys live and the caller authentication threat model.