Skip to main content

​
Deploy to LiveKit Cloud

Voiceblox includes a built-in deploy flow that packages your agent and publishes it to LiveKit Cloud in a single click. Once deployed, the agent runs persistently in the cloud — no local process required.

​
Prerequisites

Before deploying, you need three things in place:

​
1. Install the lk CLI

brew install livekit-cli

​
2. Authenticate with LiveKit Cloud

lk cloud auth
This opens a browser window to sign in. After authenticating, the CLI stores credentials locally.

​
3. Set LIVEKIT_URL

Add your project URL to .env.local: 
LIVEKIT_URL=wss://your-project.livekit.cloud
LIVEKIT_API_KEY=APIxxxxxxxxxx
LIVEKIT_API_SECRET=your-secret
You can find these values in the LiveKit Cloud dashboard.

​
Deploying your agent

  1. Open the Voiceblox builder and click Deploy in the toolbar.
  2. The dialog checks your setup automatically. All three requirements must show a green checkmark.
  3. Select a region (US East, EU Central, or AP South).
  4. Click Deploy to LiveKit Cloud.
The deploy log streams in real time. When it finishes, you’ll see the success screen with a link to the agent in the LiveKit Cloud dashboard.

​
How it works

When you click Deploy, Voiceblox:
  1. Packages the Python agent source files into a temporary directory
  2. Serializes your current flow as VOICEBLOX_CONFIG (a JSON string)
  3. Runs lk agent create (first deploy) or lk agent deploy (subsequent deploys)
  4. The lk CLI uploads the agent to LiveKit Cloud and sets the secrets
The deployed agent registers with agent_name="voiceblox". LiveKit Cloud dispatches jobs to it when new rooms are created.

​
API keys as secrets

Any provider API keys you’ve entered in the builder (OpenAI, ElevenLabs, Deepgram, etc.) are uploaded as LiveKit Cloud secrets during deployment. The running agent reads them from environment variables — they are never stored in plaintext in the agent code.

​
Agent config

Your flow configuration is stored as the VOICEBLOX_CONFIG secret. The agent reads it on startup and builds the LLM, TTS, and STT pipeline from it.

​
Testing the deployed agent

After deploying, you can test the live cloud agent directly from the builder:
  1. Open the Test Panel (microphone icon in the toolbar).
  2. Switch to the Production tab.
  3. Click Start.
This creates a real LiveKit room and dispatches it to your deployed agent. You’re talking to the actual cloud-hosted agent, not a local process.

​
Redeploying after changes

After modifying your flow, click Deploy again. Voiceblox automatically detects that the agent already exists and runs lk agent deploy to update it in place. If the agent was deleted from LiveKit Cloud, the deploy falls back to lk agent create automatically.

​
Troubleshooting

IssueFix
”lk CLI not installed”Run the install command for your platform (see above)
“Not authenticated”Run lk cloud auth
”LIVEKIT_URL not configured”Add LIVEKIT_URL=wss://... to .env.local
Deploy fails with “failed to get agent”The dialog retries automatically with lk agent create
Production test shows no activityEnsure the deploy completed successfully and the agent is listed in the LiveKit Cloud dashboard