Skip to main content
Use this after building your agent, or with an existing named LiveKit voice agent. You need your organizer’s Chert project UUID, owner/admin access, and an assigned FaceTime line. See Projects and lines.

​
1. Install and sign in once

Use macOS or Linux. The CLI supports Node 22.12+ in the 22.x series, or 24.x; the JavaScript starter uses 22.23.2 or 24.x. Native Windows is not supported. Check node --version; if you use nvm, select the same version in both terminals.
Expect chert 0.1.0-beta.3. Choose browser sign-in, compare the displayed code, select your assigned Chert project, and approve. In a remote shell, chert login --device prints the address and code. You do not need to copy a browser session token for normal sign-in.

​
2. Check the connection from your agent folder

From your agent’s folder, where you created .env.local:
No separate setup step is needed in beta.3. The CLI reads LIVEKIT_URL, LIVEKIT_API_KEY, and LIVEKIT_API_SECRET from .env.local (or .env) in this folder and uses the Chert project you approved at sign-in. It reports which file it used. Keep these values in the same LiveKit project as your agent. Existing shell LIVEKIT_* values override the file. If you previously ran chert setup, its saved project and file path still take priority. To switch to folder loading, run chert setup --clear after stopping any active connector. This keeps your sign-in. See credential loading for explicit files and optional setup when running from elsewhere. Plain doctor is read-only. Check that login, project, line, online worker and LiveKit checks pass. The agent check is skipped until you supply --agent. Resolve busy/offline lines with your organizer before continuing.

​
3. Keep two terminals running

​
Terminal A: agent

In the agent folder:
These are the supplied starter’s scripts. Use your own startup command for an existing agent. Wait for successful registration with LiveKit. Leave this terminal running; Chert does not start the program for you.

​
Terminal B: Chert

Open a second terminal in the same folder, using the same Node version:
Replace team-otter-agent with your exact registered dispatch name. doctor --agent runs a real agent job in a temporary room and may incur provider usage. It checks membership, not a full conversation. Keep this terminal running too. Wait for both of these messages before calling:
Generic chert dev automatically prepares and refills waiting rooms. Do not add --muse to the student starter: that flag is for a separately integrated Muse agent, with one prepared session per run. It is not a general avatar switch.

​
4. Test two real calls

  1. Place a FaceTime Audio call to the exact address assigned by your organizer.
  2. After connection, say hello. The starter waits for the caller to speak first.
  3. Ask a question related to your agent’s instructions and a follow-up. Confirm it responds to your actual words, then try interrupting once.
  4. Hang up from the caller’s device. Wait for Call ended: room removed. in Chert.
  5. Wait for a new waiting-room message, then make a second call. Confirm it begins a fresh conversation and cleans up again.
“Connected” and a successful doctor check are not substitutes for this test. This starter is audio-only; it does not provide avatar video. If no reply arrives, check the agent terminal for model/key/credit errors before trying repeatedly.

​
5. Stop or change your agent

End the call first. Press Ctrl+C in Terminal B and wait for:
Then stop the agent in Terminal A. To edit, change its instructions or tools and restart both terminals so a previously prepared room does not use old code. For the next session, start the agent, then run the short command again:
If cleanup or release remains pending, preserve ~/.chert and ask your organizer for help. Do not delete state to dismiss the error or let another team take over before resolving it.

​
Common problems

For help, share Node/CLI versions, agent name, call time, and relevant error lines. Never share tokens, API keys, .env.local, or unsanitized logs.