Skip to content
RTC Agent LogoRTC Agent LogoRTC Agent

Getting Started

Getting RTC Agent up and running takes two steps: deploy the Server → embed the frontend component.

Choose a Deployment

Section titled “Choose a Deployment”
DeploymentUse CaseDependencies
Docker Single Instance (recommended)Quick demo, small-scale deploymentDocker
Build from SourceLocal development & debuggingGo 1.27, PostgreSQL, Redis
Docker Distributed ClusterMulti-Worker testing, production validationDocker

Prerequisites

Section titled “Prerequisites”
  • Docker — Docker Desktop or equivalent recommended
  • LLM API Key — Claude or OpenAI-compatible API key

For source builds, you also need Go 1.27+, PostgreSQL 17+ (with pgvector), and Redis 7+. See the Source Build Guide.

Docker deployments include a built-in mock-oauth2 as a sample auth service for quick demos. Production environments require your own OAuth2 service — see Authentication for details.

Step 1: Deploy the Server

Section titled “Step 1: Deploy the Server”

1. Clone & Prepare Configuration

Section titled “1. Clone & Prepare Configuration”
终端窗口
git clone https://github.com/rtc-agent/server.git
cd server
cp etc/config.example.yaml etc/config.docker.yaml

Edit etc/config.docker.yaml and fill in your LLM API Key:

database:
  dsn: "postgres://rtc_agent:rtc_agent@postgres:5432/rtc_agent?sslmode=disable"
  auto_migrate: true


redis:
  addr: "redis:6379"


llm:
  provider: "claude"           # or "openai"
  api_key: "${LLM_API_KEY}"   # Injected via env var — set LLM_API_KEY before starting
  model: "claude-sonnet-4-20250514"

Docker config loading: Compose mounts etc/config.docker.yaml directly as /app/etc/config.yaml inside the container, so this file must be a complete configuration (copy from config.example.yaml and modify).

🔐 API Key security: api_key supports ${ENV_VAR} syntax to reference environment variables, avoiding plaintext keys in config files. Set export LLM_API_KEY="your-key" before starting — Docker Compose automatically passes the variable into the container.

2. Start

Section titled “2. Start”
终端窗口
docker compose up -d

Compose will automatically:

  1. Start PostgreSQL and Redis
  2. Run database migration (init container)
  3. Start the Server container (port 8888)

3. Verify

Section titled “3. Verify”
终端窗口
curl http://localhost:8888/healthz
# {"status":"ok"}

Step 2: Embed the Frontend Component

Section titled “Step 2: Embed the Frontend Component”

With the Server running, add the <rtc-agent> component to your web page to get an AI assistant:

<!-- Import the component -->
<script type="module" src="https://cdn.example.com/rtc-agent/index.js"></script>


<!-- Minimal setup -->
<rtc-agent></rtc-agent>

Customize theme and title:

<rtc-agent theme="dark" app-label="My AI Assistant"></rtc-agent>

The component automatically connects to the Server on the current page’s domain (defaults to localhost:8888).

Full attribute, event, and CSS variable reference: Web Component API.

Other Deployment Options

Section titled “Other Deployment Options”

Build from Source

Section titled “Build from Source”

For scenarios where you need to develop and debug on the Server side. Requires Go 1.27+.

→ See Source Build Guide

Docker Distributed Cluster

Section titled “Docker Distributed Cluster”

2 Server containers + Nginx load balancing + full observability stack (Jaeger, Prometheus, Grafana) for validating multi-Worker distributed capabilities.

→ See Distributed Cluster Deployment

Configuration Reference

Section titled “Configuration Reference”

For the full configuration options, see etc/config.example.yaml.

ConfigDescriptionRequired
database.dsnPostgreSQL connection string✅
redis.addrRedis address✅
auth.jwt_secretJWT signing key (use a strong random value in production)✅
llm.providerModel provider: claude or openai✅
llm.api_keyLLM API key✅
llm.modelModel name✅
tracing.enabledEnable OpenTelemetry tracingOptional
embedding.enabledEnable vector retrieval (User Memory)Optional

🔐 Production security: Before deploying to production, ensure HTTPS is enabled, configure a proper OAuth2 provider (not Mock), use a strong random jwt_secret, and set CORS allowlists.

Troubleshooting

Section titled “Troubleshooting”

curl healthz not responding?

  • Docker deployment: Check container status with docker compose ps, confirm all containers are healthy
  • Check Server logs: docker compose logs server
  • Confirm port 8888 is not in use: lsof -i :8888

LLM call errors?

  • Check that api_key is correctly filled in (no extra spaces in YAML)
  • Confirm model name matches your API plan (e.g., claude-sonnet-4-20250514 requires a valid Claude API subscription)
  • If using OpenAI, confirm provider is set to "openai" and api_key is an OpenAI key

PostgreSQL connection failed?

  • In Docker deployment, the dsn hostname should be postgres (Docker service name), not localhost
  • Confirm the PostgreSQL container is running: docker compose ps postgres

Frontend component cannot connect to Server?

  • Confirm the Server and web page are on the same domain, or CORS is configured
  • Open browser DevTools and check Console and Network panels for errors

Next Steps

Section titled “Next Steps”