Getting Started

Practical setup · copy-paste commands · Bun + TypeScript

Chat Agent Relay sits between your chat platform and your AI agent. This guide gets you from zero to a running server: install dependencies, wire Slack and OpenAI, start the process, verify with tests or Docker, and hit the HTTP API.

Prerequisites

Before you start, you need:

• Bun — runtime and package manager for this project.
• A Slack app with a bot token and app-level token (Socket Mode).
• An OpenAI API key (or compatible endpoint via optional env vars).

Clone the repo if you have not already:

Installation

Install all workspace dependencies from the repository root:

That pulls everything the monorepo needs so you can run the server and the full test suite.

Configuration

Create a .env for the server (start from .env.example in packages/server if the repo provides one). At minimum, set:

• SLACK_BOT_TOKEN — Slack bot token (prefix xoxb-).
• SLACK_APP_TOKEN — Slack app-level token for Socket Mode (prefix xapp-).
• OPENAI_API_KEY — OpenAI secret key (prefix sk-).

Optional tuning (only if you need them):

• OPENAI_BASE_URL — non-default API base (e.g. proxies or compatible providers).
• OPENAI_MODEL — model name override.
• CAR_STREAMING — control streaming behavior.
• CAR_API_PORT — HTTP API port (default is commonly 3000).
• CAR_POLICY_CONFIG — path or inline policy configuration for governance rules.

Running the server

Start Chat Agent Relay from the server package so Bun resolves the right entrypoint and env:

When it is up, the HTTP API is available on the configured port (typically localhost:3000). Use /api/health to confirm the process is live.

Testing

Run the full test corpus from the repository root to validate contracts and behavior across packages:

Use this after dependency upgrades or local changes to ensure nothing regressed at the boundaries.

Docker

To run with containers instead of a local Bun process:

Mount or inject the same environment variables your .env would provide so Slack and OpenAI credentials reach the container.

CLI: car-server

The server binary supports the usual operational flags:

• car-server --help — usage and subcommands/options.
• car-server --version — print the build or package version.
• car-server --check-config — validate configuration without fully starting long-running services.
• car-server --dry-run — exercise startup paths safely where supported.

HTTP API

With the server listening (default http://localhost:3000), you can:

• Health — GET /api/health for a quick liveness check.
• Conversation events — GET /api/conversations/:id/events to inspect the event stream for a conversation.
• Audit — GET /api/conversations/:id/audit for audit-oriented views of the same conversation.

Replace :id with your conversation identifier from Slack or your channel adapter.

Connect your agent

If your agent has an HTTP endpoint, you can connect it without writing any adapter code. The built-in GenericHttpBackend supports:

• Custom headers — Authorization, API keys, or any custom header your agent expects.
• Custom request body — a builder function that transforms the user message into whatever JSON shape your agent accepts.
• Response field extraction — a dot-path (e.g. "result.text", "answer") to extract the reply from your agent’s JSON response.

For non-HTTP protocols or more advanced integration patterns:

• New chat surface — add a channel adapter that turns platform webhooks or sockets into Chat Agent Relay’s canonical message flow. Your users stay on Teams, Discord, or a custom web client; Chat Agent Relay keeps one internal shape.
• New agent backend — implement the BackendAdapter interface for protocols beyond HTTP while policy, routing, ledger, and delivery stay consistent.

← Back to home Repository