Capability status
This YAML is the machine-readable summary for agents. “Verified” describes the published package/help/fixture or loopback checks listed below; it does not mean that a real customer line, message, or call was exercised.Prerequisites and bootstrap
- A macOS or Linux host and access to the intended Chert project. Native Windows is unsupported.
- Node.js 22.12+ (22.x), 24.x, or 26.x for the CLI when using npm/pnpm/npx; the bundled starter supports Node 22.23.2 or 24.x. Bun 1.4.0 package commands were exercised locally.
- For voice, a registered LiveKit agent and its existing LiveKit project values.
- For the SDK channels, separate iMessage and FaceTime service credentials. A
shared
CHERT_PROJECT_IDis context; it does not bind or authorize the two credentials together. - Explicit owner approval before browser/device sign-in, phone verification, paid provider activity, messages, or calls.
beta tag pointed to beta.10 while latest
pointed to beta.6. Use @beta intentionally in npm/Bun commands; do not omit
the tag. The tested pnpm add @trychert/facetime@beta resolved beta.6, so the
pnpm example pins beta.10 explicitly.
login approves one project for this computer. Use it for an existing project.
Use onboard only for a new setup after the owner approves the phone-verification
step. A human must complete the browser and send any displayed verification
code; an agent must not send it, ask the owner to paste it into chat, or claim
verification succeeded while the command is pending. --skip-demo skips the
hosted demo request, not verification or line allocation. If the service cannot
allocate a line, stop and report that exact result. Do not create a second
onboarding to retry an uncertain request.
new creates a generic LiveKit voice-agent starter; it does not integrate an
existing OpenClaw, Hermes, Muse, or other personal-agent runtime. It refuses to
overwrite a non-empty target. A clean starter’s npm start is separate from
chert dev; neither command installs an always-on service.
Temporary generated wrapper
Until a universal personal-agent CLI ships, an integrating coding agent may create a project-local wrapper in a new, empty directory. The names below are commands generated in that project, not commands supplied by Chert:chert dev --json emits newline-delimited JSON records with
schema_version: 1 and command: "dev". Call events include call_incoming,
call_accepted, call_declined, call_ended, call_media, and
call_bridge_ready. The last means Chert wrote the bridge-ready room signal;
it is not proof that audio/video worked or that the caller heard the agent.
Session records include dev_ready, dev_stopped, cleanup_pending, and
release_failed. On shutdown, a second interrupt reports that release is still
underway; a third can exit without releasing. Do not claim cleanup until the
terminal record confirms it.
The wrapper should use a project-local chert-agent executable (for example,
./chert-agent health) and emit JSON Lines with a documented schema. That output
schema is local to the generated project, not a Chert API guarantee. Persist only
non-secret project/line/agent identifiers and stable idempotency keys in an
owner-only state file. Reuse ~/.chert and the same onboarding intent. Automatic
service restart, durable message watching, and recovery after host reboot remain
unverified; do not promise them or invent a supervisor integration.
Secrets, consent, and identity
Create or edit.env.local locally and require mode 0600. Add .env.local and
.env* to .gitignore before writing secrets. Keep LIVEKIT_API_SECRET,
OPENAI_API_KEY, CHERT_API_KEY, CHERT_FACETIME_TOKEN, and all login/device
credentials out of prompts, command arguments, stdout/stderr, screenshots, logs,
and version control. Never print an env file to diagnose it; report variable
names and whether values are present, not their values.
The CLI login credential, iMessage API key, FaceTime token, and LiveKit API
secret are different credentials. The SDK’s project ID is context only for the
iMessage client. No Chert-managed owner-contact allowlist or cross-channel
consent policy is currently provided. The personal-agent application must derive
its persona and handlers from the owner’s explicit brief and relevant repository,
and enforce the approved recipient/contact policy locally.
Before every real outbound message or call, show the exact recipient, content or
call purpose, and expected cost/impact, then wait for that action’s explicit
confirmation. Setup consent is not send/call consent. doctor --agent dispatches
a real agent job; ask before using it. Do not test against a real person or line
without approval.
Project, line, and LiveKit lifecycle
Choose the project the owner approved.chert login signs this computer into
that project. chert-sdk facetime lines and workers inspect existing access;
they do not assign a line. chert doctor --json checks readiness predicates,
but a healthy response does not prove two-way media. A project must already have
the eligible line and worker required by chert dev.
Run the personal agent using its own supported host/runtime. Put its LiveKit
values in the same project’s .env.local; Chert does not start or deploy the
personal agent. Start the foreground connector with chert dev --agent NAME --json. It handles incoming calls on an assigned line. It is not an outbound
FaceTime call command and is not a background service. The owner must accept or
place a real test call only after explicit confirmation. Audio/video success must
be confirmed during the call, not inferred from identity, health, or connection
status.
For shutdown, send SIGINT/Ctrl+C to the wrapper-owned chert dev process and
wait for its terminal dev_stopped record. Preserve state if it reports
cleanup_pending or release_failed. This drains the connector when cleanup is
confirmed; it does not release the project allocation or phone number. There is
no verified CLI command to release that allocation; ask the project owner/admin.
iMessage and FaceTime API boundaries
The SDK CLI reads existing FaceTime identity, lines, and workers:facetime status checks identity, not media readiness. There is no published
SDK call-start, call-watch, or call-end method. chert dev is the supported
incoming-call connector path when its line is ready.
An explicitly approved iMessage send may use:
queued receipt. It means accepted for queueing,
not sent, delivered, or read. The client does not retry automatically. On timeout
or an unconfirmed response, preserve the same idempotency key and reconcile with
the service/operator before trying again. The published CLI has no generic
iMessage watch or receive command; do not poll guessed endpoints or infer
delivery from queue acceptance.
Structured output and recovery
chert --json emits one JSON record per line with schema_version: 1 and
command; chert dev --json is an event stream. Errors go to stderr as
structured codes/actions. SDK channel commands emit JSON objects by default and
sanitize errors. The local wrapper should preserve these streams, never parse
human prose as a success signal, and keep its own stdout schema separate.
For diagnostics, begin with
chert guide fix and chert doctor --json. Capture
timestamps, command names, project/line IDs only when safe, error codes, and
redacted event records. Redact phone numbers, message bodies, tokens, URLs with
credentials, .env.local, and provider responses. Never attach raw process
environments or unfiltered logs.