VoiceThere

Quickstart

This guide walks from zero to a live cloud voice session: authenticate the CLI, create and link a project, build an agent bundle, deploy to VoiceThere cloud, and connect with the browser client. For dashboard-only template seeding, see Agent templates.

1. Install packages

npm install -g @voicethere/cli
npm install @voicethere/agent

See npm packages for the full install matrix.

2. Log in

voicethere login

Browser device approval stores a personal API key. Details: CLI login.

3. Create and link a project

cd my-voice-agent
voicethere projects create "My voice agent" --slug my-voice-agent
# writes .voicethere/config.json with project id and dist/agent.js bundle path

Or pick an existing project: voicethere projects use <project-uuid>.

4. Write and build the agent

# Minimal agent (src/agent.ts)
import { defineAgent } from "@voicethere/agent";

export default defineAgent({
  async onUserSpeechFinal({ text, say }) {
    await say("You said: " + text);
  },
});

npx @voicethere/agent build --entry src/agent.ts --outfile dist/agent.js

5. Validate, upload, deploy

voicethere build validate
voicethere build upload -m "Initial quickstart build"
voicethere build list
voicethere build promote <build-uuid-from-list>
voicethere deploy --wait

deploy --wait rolls the active build to cloud session workers and blocks until rollout completes.

6. Optional: environment and secrets

voicethere projects environment create AGENT_GREETING "Hello from quickstart"
voicethere projects secrets create AGENT_OPENAI_API_KEY sk-...
voicethere deploy --wait

See Agent environment & secrets.

7. Connect a browser client

Create a client API key in the dashboard (vthc_…) — safe to embed in web apps. Then start a session and connect:

npm install @voicethere/client

# Start session (replace host, project id, and key)
curl -sS -X POST "https://app.voicethere.dev/v1/sessions" \
  -H "Authorization: Bearer vthc_..." \
  -H "Content-Type: application/json" \
  -d '{"project_id":"<project-uuid>"}'

Use the returned join token and signaling URL with connectVoiceSession — see Browser client.

Next steps

← All documentation