Chat Server

• Setup
  • Configure
• Client
  • VitePress Plugin
• Development
• Support
• Contributing

Proxy Chat Server designed to work with the VitePress Chat plugin.
Secure your API key while live-streaming responses to the client.

Works with Claude, Gemini, OpenAI, or any OpenAI Compatible Provider.

💯 100% Free to use with Zen OpenCode or Gemini Free Tier!

To get started Setup and Configure the server. No API Key required!

• Client: https://github.com/cssnr/vitepress-chat
• Server: https://github.com/cssnr/chat-server

Features

• Works with Claude, OpenAI, Gemini and OpenAI Compatible Providers
• Live Stream Results to Client
• Automatic Input Token Caching
• Automatic Retry on API Failures
• Deploy with Docker or Node
• Supports Multiple Clients Simultaneously
• Plus all the Client Features

Built with the AI SDK.

Setup

💡 The server works out-of-the box with NO environment variables.

With Docker.

docker run --rm cssnr/chat-server:latest

With Docker Compose.

services:
  chat:
    image: cssnr/chat-server:latest
    environment:
      MODEL: 'gemini-2.5-flash'
      GOOGLE_GENERATIVE_AI_API_KEY: 'xxx'

With Node.

npm i
npm start

Note: you will need to export your environment variables or set them in the settings.env file.

For a Docker Swarm + Traefik + Basic Auth example see the docker-compose-swarm.yaml.

For a Portainer Deploy workflow see the .github/workflows/deploy.yaml.

Configure

💡 All variables are optional. The default big-pickle model works with NO API Key.

Environment Variables.

Variable	Default	Description
MODEL	big-pickle	Model to Use
BASE_URL	https://opencode.ai/zen/v1	OpenAI Compatible Provider Base URL
PROVIDER_OPTIONS	-	Provider Options JSON String
MAX_TOKENS	-	Max Output Tokens
INSTRUCTIONS	-	Fallback System Instructions
AI_SDK_LOG_WARNINGS	-	Disable SDK Warnings
CORS_ORIGINS	-	Allowed CORS Origins (supports *)
PORT	3000	Server Port

You must also set the API key for the MODEL you select.

Variable	Description
ANTHROPIC_API_KEY	Claude Models
GOOGLE_GENERATIVE_AI_API_KEY	Gemini Models
OPENAI_API_KEY	OpenAI Models
PROVIDER_API_KEY	OpenAI Compatible Provider

The PROVIDER_API_KEY is optional for free-tier models like big-pickle.

PROVIDER_OPTIONS

Provider Options: https://vercel.com/docs/ai-gateway/models-and-providers/provider-options

For example, to disable "Reasoning" on big-pickle model.

{ "zen": { "thinking": { "type": "disabled" } } }

You may need to wrap the variable in single quotes.

PROVIDER_OPTIONS='{"openai":{"serviceTier":"flex","reasoningEffort":"low"}}'

You are responsible for providing valid options for the chosen model. The SDK supports providing provider options for multiple provider simultaneously. The value is only checked for valid JSON at startup and will fail at runtime if it contains invalid options.

Client

To send System Instructions from the client, add them to the body.

const chat = new Chat({
  transport: new DefaultChatTransport({
    api: 'https://chat-server.cssnr.com/',
    headers: { Authorization: 'Basic Abc123=' },
    body: { system: 'You are a helpful assistant.' },
  }),
})

VitePress Chat Plugin

The client is currently available as a VitePress Plugin.

• https://github.com/cssnr/vitepress-chat

Development

This works with no configuration using the big-pickle model.
You can set your environment variables in the settings.env file.
If using big-pickle for testing it is much faster to disable reasoning.

PROVIDER_OPTIONS='{"zen":{"thinking":{"type":"disabled"}}}'

In all cases you can set the PORT environment variable.

With Node run.

npm run dev

Point your client to: http://localhost:3000/

With Docker compose (you may need to touch settings.env).

docker compose -f docker-compose-dev.yaml up --watch --build --remove-orphans

Point your client to: http://localhost/

Building

To build and test the docker image run.

bash build.sh
docker compose up

Support

If you run into any issues or need help getting started, please do one of the following:

• Report an Issue: https://github.com/cssnr/chat-server/issues
• Q&A Discussion: https://github.com/cssnr/chat-server/discussions/categories/q-a
• Request a Feature: https://github.com/cssnr/chat-server/issues/new?template=1-feature.yaml
• Chat with us on Discord: https://discord.gg/wXy6m2X8wY

Contributing

Please consider making a donation to support the development of this project and additional open source projects.

For a full list of current projects visit: https://cssnr.github.io/