English | 简体中文
vertc is the Volcengine RTC developer-workflow CLI for creating,
configuring, diagnosing, and running AI audio/video projects. The current
release turns the official rtc-aigc-demo web voice-agent template into a
guided, runnable workflow for both developers and coding agents.
Current scope:
voice-agent × web. More scenes and platforms will be added only after their end-to-end workflows are ready.
Quick start · Agent & CI · Commands · Security · Documentation · Contributing
- One guided workflow — scaffold a pinned official template, configure it from the Console, check readiness, and start local development.
- Console-aware setup — Sign in once, then let the first
devrun discover your RTC applications and conversational-AI agents and configure the project. - Diagnostics first —
doctorreports evidence-based PASS/WARN/SKIP/UNKNOWN/FAIL checks;explain-errorprovides an offline SDK and conversational-AI error catalog. - Agent-native output — JSON is the default, stdout stays machine-readable,
errors have stable
error.codevalues, and official Skills provide workflow playbooks.
- macOS, Linux, or Windows on amd64 or arm64
- Node.js 16 or later for the recommended npm installation
- Go 1.25.12 or later only when installing or building from source
- A Volcengine account with an RTC application; a conversational-AI agent is
optional because
devcan use the built-in default scene - Access to GitHub Releases for npm installation and GitHub codeload for the first template download; later scaffolds can reuse the verified local cache
Install the prebuilt binary from npm:
npm install -g @volcengine/rtc-cli
vertc version --format prettyThe installer downloads the binary matching the package version and current
platform, then verifies it against the release checksums.txt before making it
available as vertc.
You can also build from source:
git clone https://github.com/volcengine/VolcEngineRTC_CLI.git
cd VolcEngineRTC_CLI
make build
./bin/vertc version --format prettyManually managed binaries are not overwritten by vertc update; the command
prints the appropriate upgrade guidance instead.
You can start without creating a conversational-AI agent first. When the
signed-in account has no agent, dev uses the built-in default scene and links
to the Console for later customization.
# 1. Create the project from the verified rtc-aigc-demo template.
vertc init ./my-agent --scene voice-agent --platform web --format pretty
cd my-agent
# 2. Sign in and store the refreshable Signin token.
vertc auth login --format pretty
# 3. On first run, configure an RTC application and optionally select agents;
# vertc then writes the local runtime configuration and starts web + server.
vertc dev --format prettyThe first positional argument to init is the target directory; here the
project is scaffolded into ./my-agent.
When authorization is needed, interactive auth login asks whether to open a
browser, use a manual link/code flow, or cancel. In an agent, remote, or
headless session, obtain user consent and run vertc auth login --browser=open
or use the resumable manual flow; no UI opens implicitly:
# Agent turn 1: return data.authorization_url to the user, then exit.
vertc auth login --browser=manual --start
# Agent turn 2: send the code returned by that URL to the saved transaction.
printf '%s\n' '<authorization-code>' | vertc auth login --resumeThe second command must use --resume: starting --browser=manual again creates
a different OAuth state and invalidates the code from the first URL. A pending
manual authorization expires after --timeout (five minutes by default) and can
be consumed only once. The first interactive dev run automatically uses a
unique RTC application and prompts when a choice is required. If one or more
conversational-AI agents exist, the user chooses which to use; if none exist,
the built-in default scene is used. Run vertc dev --reconfigure to select
again later; existing bot scene files are preserved.
When a usable Signin token is already stored, auth login reuses it (refreshing
it when near expiry) without prompting or opening a browser. Use
vertc auth login --force with an explicit browser mode to reauthorize or
switch accounts.
Signin access and refresh tokens default to the protected
$VERTC_HOME/auth.json file (~/.vertc/auth.json when VERTC_HOME is unset).
Choose the operating-system credential store explicitly with
vertc auth login --store=keyring; later commands keep using the selected store.
In an agent or another non-interactive terminal, run vertc dev. A
vertc.dev.selection_required error contains public candidates in
error.details.apps or error.details.bots; ask the user to choose, then retry
with vertc dev --app-id <id> or vertc dev --bot-id <id>.
The signed-in CLI retrieves AppKey itself; never send AppKey to an agent or put
it in command arguments.
The generated project contains the full rtc-aigc-demo web UI and local server.
After first-run configuration, vertc dev starts both processes; each browser
page session receives isolated room, user, token, task, and target-user
identities. Run vertc doctor --format pretty whenever setup or runtime fails;
it diagnoses without modifying the project.
See Voice-agent projects for the generated layout,
runtime modes, manual configuration, and advanced identity management.
Register the official workflow Skill using either form:
The published Skill identifier is byted-interactai-guide.
# From the installed CLI (no repository access required)
vertc skills sync
# Or directly from the public repository
npx skills add volcengine/VolcEngineRTC_CLI -g -yAgent and automation runs should keep the default JSON format:
vertc init ./my-agent --scene voice-agent --platform web
cd my-agent
vertc auth status
vertc dev
vertc doctor- stdout contains one JSON envelope with
okplusdataorerror. - progress, warnings, and recovery hints go to stderr.
- failures use non-zero exit codes and stable
error.codevalues. - side-effecting commands accept the global
--dry-runflag. VERTC_NO_UPDATE_NOTIFIER=1andVERTC_NO_SKILLS_NOTIFIER=1suppress additive lifecycle notices when required by a controlled environment.
See Automation and structured output for headless authorization, non-interactive resource selection, JSON envelopes, failure routing, and Skill contracts.
| Command | Purpose |
|---|---|
init [dir] --scene <scene> --platform <platform> |
List or scaffold supported project templates into [dir]; supports --dry-run |
auth login [--browser=ask|open|manual] [--start|--resume] [--store=file|keyring] / auth status/logout |
Manage Volcengine Signin credentials with explicit UI, resumable Agent login, and storage choices |
doctor [cli|project] |
Diagnose CLI and project readiness without modifying the project |
dev [--reconfigure] [--app-id <id>] [--bot-id <id>] |
Configure RTC resources and run the template; unambiguous choices are automatic, selection errors return public candidates, and zero agents use the built-in default scene |
explain-error <code> |
Look up Web SDK and conversational-AI errors offline |
skills list/read/sync |
Inspect, install, or refresh the official Skill content embedded in this release |
update [--check|--force] [--dry-run] |
Check, preview, or update npm-managed installs and synchronize official Skills |
version |
Print build version, commit, and date |
Run vertc <command> --help for prerequisites, examples, and advice about when
to use or avoid each command. Advanced manual/debugging commands remain hidden
from the main help so the supported onboarding path stays small.
vertc deliberately separates project metadata, runtime secrets, scene data,
and Signin credentials:
| Location | Contains | Safety boundary |
|---|---|---|
vertc.config.yaml |
Non-secret project metadata and CLI-managed RTC/agent identity references | Safe to review; secrets are referenced through ${ENV} placeholders |
.env.local |
Local runtime values such as RTC_APP_ID and RTC_APP_KEY |
Gitignored and written with restricted permissions; never commit it |
server/scenes/*.json |
VoiceChat ASR/LLM/TTS and agent configuration selected from the Console | Server-side scene configuration; review before sharing |
$VERTC_HOME/auth.json (default ~/.vertc/auth.json) |
Selected store and, in file mode, Signin access/refresh tokens |
Directory 0700, file 0600; treat it like a password and never commit it |
OS credential store (optional keyring mode) |
Signin access and refresh tokens | Used only after explicit auth login --store=keyring selection |
RTC_APP_KEY is never written to vertc.config.yaml, a VITE_* frontend
variable, logs, or structured output. It may be stored in the gitignored
.env.local file so new shells and the companion server can use it. Exported
process environment variables take precedence over values in that file. Never
provide AppKey in chat or command arguments.
For vulnerability reporting, see SECURITY.md. Do not include credentials, tokens, private endpoints, or sensitive Console data in a public issue.
- Voice-agent projects — generated layout, first-run configuration, runtime modes, and identity behavior
- Automation and structured output — JSON envelopes, error routing, dry runs, notices, and Skills
- Troubleshooting — installation, authentication, template, credential, and runtime recovery
- CONTRIBUTING.md — setup and contribution recipes
- AGENTS.md — architecture and repository engineering contracts
- SUPPORT.md — where to ask questions or report bugs
- CHANGELOG.md — release changes
make build # build ./bin/vertc with version metadata
make test # unit and end-to-end tests
make check-error-codes # validate the stable error.code catalog
make ci # run the complete repository gateContributions are welcome. Read CONTRIBUTING.md before opening a pull request, and use SUPPORT.md to choose the right channel for questions, bugs, feature requests, and security reports.
This project is licensed under the MIT License.