Skip to main content
Advanced: use this when your application owns session creation and cleanup. For a named LiveKit agent, start with chert dev. The CLI receives call requests from Chert and invokes your application callbacks. Your application returns a ready LiveKit session; the wrapper does not create rooms or dispatch agents. Both inbound FaceTime Audio and FaceTime Video are supported without a webhook. Chert passes the requested media to prepare as call.media. Use a line enabled for the video directions you need and configure your agent to publish or consume those tracks; see Audio, video, and caller vision.

Before you start

chert byor uses manual connector enrollment; for a named LiveKit agent, chert dev needs no enrollment step. Use Node 22.12+ (22.x), 24.x or 26.x, macOS or Linux, and a durable local state directory. Start your agent using its normal command.
1

Install and initialize

From your application’s directory, install the published package:
This creates chert.json and chert-handler.ts. It refuses to overwrite existing files. Keep the config and state out of version control.
2

Connect the generated callbacks

Edit chert-handler.ts to call your application’s existing session logic. No HTTP server is needed.call.media.audio is true; call.media.video is true for FaceTime Video and false for FaceTime Audio. Preserve that choice in your session preparation. Return ready: true only after the application is ready for the requested media, or decline if it cannot support the call. The CLI does not add camera capture or vision processing to your agent.A ready-session response has this shape (values come from your application):
Use a non-secret session reference and a short-lived, call-scoped token. Expiry is an absolute Unix timestamp in milliseconds and must fit the token lifetime. Return { action: "decline" } when you cannot prepare the call.
The generated handler deliberately declines until you implement it. A returned accept must mean the session is actually ready. Preparation must finish within the supplied deadline and context.remaining_ms; the CLI does not make slow agent cold starts faster.
Honor context.signal and context.remaining_ms. Recovery must inspect the original operation, never repeat preparation. Report settled: true only when no further creation can complete, and cleanup: "clean" only after verifying resources are cleaned up or absent.recover() also runs during routine reconciliation of active or uncertain calls. A reconciliation read failure or unknown acceptance is not permission to delete an active room. Preserve resources until authoritative termination or applicable cancellation permits cleanup (including cancellation for expiry). Keeping an active session is not cleanup: "clean"; report settlement and cleanup separately and retain retries for failed deletion or late preparation.The installed package includes a complete session-store example in node_modules/@trychert/facetime/examples/byor/. Adapt it to your application’s durable storage and cleanup logic.
3

Compile and check

Export the handler as an ES module and point the config at its compiled JavaScript. Use your application’s existing ESM build. For a new standalone project, set "type": "module" in package.json and compile the generated file:
check is non-allocating and currently exits 3 for partial diagnostics. Read the reported checks; this alone is not a failed installation or proof of a working FaceTime call.
4

Enroll, activate, and run

Follow Manual connector enrollment to create an enrolled config and activate your chosen line. Run the connector with that config:
Keep your agent and connector running. Test a real inbound call on the intended line: confirm two-way audio and, for video, each required video direction. A caller-vision test must verify fresh frames reach your model or tool. End the call and verify cleanup before testing again.
Missing or failed health is shown as unknown, not ready. Known-unavailable health declines calls; unknown health still allows bounded per-call preparation, which must explicitly establish readiness. Unresolved cleanup blocks new calls at the preview’s capacity of one.