Sleeptalk

Get started

Quickstart

Install Sleeptalk from PyPI, choose how voice works, and start a conversation with your agent. You can keep talking while background workers research, build, and test.

Prerequisites

  • Current macOS or Ubuntu, with Python 3.11 or newer and an internet connection for setup. The PyPI install needs no Git or Node.js; your selected agent may have its own runtime requirements.
  • An agent or a model. Install and sign in to your selected agent, or use Just a model for a call without tools.
  • Speech. One key from Deepgram, Cartesia, ElevenLabs, OpenRouter, Venice, Groq, or Together both listens and speaks. Local speech needs no speech key. OpenAI Realtime or GPT Live handles voice directly with an OpenAI credential; GPT Live is browser-only preview. Setup also offers a speech-capable key it finds on the machine.
  • A microphone and audio output. This guide uses a browser on the same computer.

Check your Python with python3 --version. If Python is missing, use the release bundle under Other installation options; its installer brings Python and uv.

Install and configure

Install from PyPI

Run this once in your terminal. The virtual environment keeps Sleeptalk separate from your system Python:

Terminal
python3 -m venv ~/.venvs/sleeptalk
. ~/.venvs/sleeptalk/bin/activate
python -m pip install sleeptalk

If you already have a Python 3.11+ virtual environment active, use just the pip line. On Ubuntu, install python3-venv if Python reports that venv or ensurepip is missing, or use the release bundle below.

Start in your workspace

Replace the example path with the folder your agent should work in.

Your workspace
cd /path/to/your/project
sleeptalk

This opens the settings page to set up or choose a profile and start a call. On a host with no browser, setup runs in the terminal.

Choose your agent

Pick the agent harness you already use, or Just a model for a conversation with one model key and no tools.

Choose speech

If setup finds a speech-capable key on this machine, it lists it first, for example "use your key from ~/.hermes/.env". Otherwise pick a provider and enter its key in the masked prompt. Setup checks the key with its provider and stores it in the private credential store. Choose Local for speech with no key; setup downloads its models (about 493 MB for the default streaming Moonshine and Kokoro pair, plus runtimes). See voice modes for the Cascade, GPT Realtime, and GPT Live split.

Choose a voice and a destination

Pick a voice, then choose Web for a browser call. If Tailscale is connected on this machine, setup asks once whether to deliver browser calls over your tailnet.

Talk

Start the browser call from the settings page. Sleeptalk opens its call link in your browser. A call started from this terminal runs on localhost, with no hosted relay. Allow microphone access and start talking. Keep the terminal running; press Ctrl+C there to end the call.

Verify the call

Ask a short question and confirm that you hear the answer. Then ask the agent which folder it is working in. If the call connects but nothing answers, check the terminal for errors, then run sleeptalk doctor.

Start another call

In a new terminal, activate the environment again, then run Sleeptalk from the project you want your agent to work in:

Terminal
. ~/.venvs/sleeptalk/bin/activate
cd /path/to/your/project
sleeptalk

Choose the workspace's saved profile and start a call. Add --web, --terminal, or --discord to use another destination for one call without changing the default. Terminal and Discord need their optional extras; see Terminal audio and Discord setup.

Change settings

Change the setup
sleeptalk settings          # the settings page in this computer's browser
sleeptalk settings --terminal # the terminal wizard
sleeptalk settings --phone  # a single-use link to the same page for your phone

The settings page runs on this computer, on the loopback interface. On a phone it reaches this computer through an encrypted channel. It has a page each for the agent, speech service, voice, language, call delivery, Discord setup, behavior, and keys. See Settings and profiles.

Profiles live in ~/.sleeptalk, or in $SLEEPTALK_HOME when it is set. A repository's own config/profiles/ is used only after you run sleeptalk trust in it.

Try work that takes time

Ask for research or a build in the background, then keep discussing the next decision. On eligible Cascade calls, three workers can run at once by default and more jobs queue. Ask for progress, add instructions using the job's title, and hear the result when the conversation is quiet. Jobs stop when the call ends. See background workers.

Other installation options

Release bundle with Python and tested dependencies

Download the wheel (.whl), install.sh, and constraints.txt from the 0.1.0 release into one folder. Run this from that folder:

Terminal
sh install.sh --constraints constraints.txt ./sleeptalk-*.whl

The installer supplies uv and Python if needed and installs the command in an isolated environment. Use the full command path it prints, or open a new terminal if it updates your PATH. Then run sleeptalk from your own project. The constraints select the dependency versions tested for this release; pip without constraints resolves current compatible versions.

Source checkout for development

Clone into a separate folder, run its installer, then return to your own project before setup:

Terminal
git clone https://github.com/sleeptalklabs/sleeptalk.git /path/to/sleeptalk-source
sh /path/to/sleeptalk-source/scripts/install.sh
cd /path/to/your/project
sleeptalk

Replace the example paths with your own. A source checkout follows development rather than the published PyPI release. See Contributing.

Next steps