Reference

Architecture

Sleeptalk connects an ongoing voice conversation to your agent and workspace. Cascade uses separate listening and speaking models around your agent. GPT Realtime and the separate GPT Live browser preview let an OpenAI model handle voice and hand specialist work to your agent. See voice modes.

Conversation and background work

On eligible Cascade calls and the GPT Live browser preview, long tasks can run in fresh worker sessions of your agent while the foreground conversation continues. Three workers run at once by default and additional jobs queue. One voice reports progress and results; workers do not speak over each other. Jobs end with the call. See background workers.

One Cascade turn

The call captures your voice

A browser call, Terminal audio, or a Discord voice channel connects you to the Sleeptalk runtime. The runtime runs on the host: the computer or VPS that has access to your agent and workspace.

A provider transcribes it

The speech-to-text provider turns your audio into text. Deepgram and Cartesia stream words as you speak and decide the end of your turn from the audio. ElevenLabs, OpenRouter, Venice, Groq, and Together listen one turn at a time: Sleeptalk decides when you have finished and uploads the clip. Local speech runs Moonshine on the host.

Your agent handles the request

An adapter passes the text to the selected agent: Claude Code, Codex, Hermes, pi, Cursor, OpenClaw, a custom agent, or a model with no agent. The agent answers, uses its tools, or asks for permission according to its adapter's configuration. Sleeptalk turns the events it receives into call status and spoken updates.

Sleeptalk speaks the response

The text-to-speech provider turns the reply into audio as it streams in. Shared session logic coordinates speech, interruptions, and ongoing work across every call destination. Turn ownership lives in RealtimeSession (sleeptalk/session.py); Cascade speech behavior lives in VoicePolicyRuntime (sleeptalk/voice_policy_runtime.py).

How a browser call travels

Delivery	Path	Limit
Same machine	A package-owned server on the loopback interface. `sleeptalk` run in a terminal on the host uses it, unless the profile delivers over the tailnet.	None
Your tailnet	The same server, published under the host's tailnet name with `tailscale serve` on port 8443. No relay, no TURN.	None
Hosted relay	A single-use link through the hosted service, which relays the ticket, signaling, and TURN.	30 minutes, announced before it ends

Every start receipt names its delivery. Call audio, transcripts, and agent state travel over WebRTC between the browser and the host; the hosted relay never receives provider keys, transcripts, or workspace contents. See Web calls and security.

The settings page

There is one settings page.

On the host (sleeptalk settings --open), it is served on the loopback interface with a single-use token. It reads and writes the profile directly.
On a phone (sleeptalk settings --phone, sleeptalk host settings-link, or Advanced settings during a call), the hosted service serves the same page at https://call.sleep.talk/settings. The page opens a sealed channel to the host with a public key from the link's fragment. Every request it makes travels inside to an ordinary settings server on the host's loopback. The relay forwards ciphertext it cannot read.
An agent's key request (sleeptalk host input link, or host input start in the host's own browser) opens the same settings page on just that request.

Keys entered on it are checked with their provider, then kept in the private store: by default a file only your user can read, or the macOS Keychain or Linux Secret Service if you install sleeptalk[credentials] before the first key is saved. On a Mac the file store is excluded from Time Machine, and it can move to the Keychain later. Agent gateway tokens live in the same store. Profiles hold references, never keys. See Credentials and data.

State on the host

Profiles and state live in ~/.sleeptalk, or in $SLEEPTALK_HOME when it is set. A repository's config/profiles/ is used only after sleeptalk trust in it, and Sleeptalk never reads the working directory's .env, so a cloned project cannot choose your agent or endpoints.

Repository layout

Directory	What it is
`sleeptalk/`	The Python package and CLI, including the settings page
`tests/`	Package tests; `tests/runtime/` holds the transport and session suites
`rendezvous/`	The hosted relay (a Cloudflare Worker) and the browser call page, plus the shell that loads the settings page on a phone
`remote-entry-web/`	The page for paired remote setup (`host remote`)
`examples/`	Runnable adapter and session examples
`docs/`	Guides, contracts, and decision records

Read about turn taking, tool calls and sub-agents, OpenAI Realtime, and the separate GPT Live browser preview. For extension points, see Component and protocol reference and the component contracts.