Skip to main content

Quickstart

This walks you through getting voxa running on your laptop and making your first call.

Prerequisites​

  • macOS. It's the only supported laptop platform right now.
  • Claude Code, installed and logged in. Voxa reuses your existing Claude Code login to drive sessions, so there's no separate Anthropic API key to configure.
  • tmux. Voxa runs Claude Code sessions inside tmux. The curl installer sets it up for you (via Homebrew); otherwise run brew install tmux.

That's it for zero-config use. You don't need a Gemini API key, and you don't need to sign up for anything: the default install talks to Voxa's hosted relay, and voice is metered through Voxa's cloud rather than your own key. If you'd rather run fully on your own infrastructure, see Self-hosting.

Install​

Pick one of these three. They all end up installing the same PyPI package, voxa-code, which puts a voxa command on your PATH.

Option A: curl installer​

curl -fsSL https://voxa.space/install.sh | sh

This installs uv if you don't already have it, then runs uv tool install voxa-code. It also installs tmux (via Homebrew) if it's missing, and warns you if the Claude Code CLI isn't on your PATH. It's safe to re-run.

Option B: npm​

npx voxa-code

or install it globally:

npm install -g voxa-code

The npm package is a thin Node wrapper: it finds (or bootstraps) a Python interpreter and runs the same server underneath. Requires Node 16 or later.

Option C: uv or pip​

uv tool install voxa-code

or, to run it without installing anything permanently:

uvx voxa-code

or with pipx:

pipx run voxa-code

Get the iPhone app​

If you have an iPhone, install the native app from the App Store:

Voxa on the App Store

The native app is what gives you agent-initiated calls, meaning your phone actually rings like a phone call when Claude Code finishes. If you don't have an iPhone, or just want to try Voxa first, skip this: any phone browser works as described below.

Run it​

From a terminal on your laptop, just run:

voxa

voxa takes no flags or arguments; everything is zero-config by default. Here's what happens, in order:

  1. The server starts. Voxa boots a local server bound to 127.0.0.1:8787 (the port is only changeable via the VOXA_PORT environment variable, see the reference).
  2. It picks a way for your phone to reach the laptop. By default this is the hosted relay at api.voxa.space: your laptop dials out to it, so nothing needs to be open on your network. If you have Tailscale installed and logged in, Voxa prefers your own tailnet instead of the relay. If that path isn't reachable, it falls back to a Cloudflare quick tunnel.
  3. A QR code prints in your terminal, along with the pairing URL underneath it.
  4. The Claude Code hook installs automatically. This is what lets a finished (or blocked) Claude Code task notify Voxa so it can call you back; you'll see a confirmation line in the terminal.

Pair your phone​

  • With the app: open Voxa on your iPhone and scan the QR code in your terminal. During setup the app asks for microphone access (so you can talk on calls) and notifications (so it can alert you when Claude finishes); allow both, calls can't work without the microphone.
  • With a browser: open the pairing URL printed under the QR code directly (copy it to your phone any way you like, or just scan the QR code with your camera). It opens the same web client the app uses, right in Safari or Chrome.

Try it by voice​

Once you're connected, some things to say:

  • "Use my open terminal." Voxa attaches to a Claude Code session you already have running, instead of starting a new one.
  • Pick a project folder. Say something like "start a session in my notes app project" and Voxa will list matching folders or start one for you.
  • Send a task. "Add a dark mode toggle to the settings screen" (or whatever you actually need). Voxa hands it to Claude Code and gets out of the way.
  • Hang up. Close the app or the browser tab. Claude Code keeps working on your laptop, and when it's done, your phone rings again with the result.

Stop the server​

Press Ctrl-C in the terminal where voxa is running. That shuts down the server and any tunnel it opened.

Note that this is different from hanging up the phone: disconnecting your phone doesn't stop anything. The Claude Code session keeps running on your laptop as long as voxa itself is up, exactly so you can put the phone down mid-task and get called back later.

Next steps​

  • How Voxa works for the full architecture and what happens on a call.
  • Troubleshooting if the QR code won't scan, the tunnel won't connect, or the hook doesn't fire.