Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/Evincere/klisk/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The klisk serve command starts a production server that provides:
  • Chat UI at the root URL
  • REST API at /api/chat with SSE streaming
  • WebSocket endpoint at /ws/chat
  • Embeddable widget via /widget.js
  • Health check at /health
  • API key authentication (optional)
The production server is optimized for deployment with no file watcher or Studio overhead.

​
Starting the Server

​
Basic Usage

klisk serve
Starts the server on port 8080 (or $PORT if set): 
  Chat UI: http://0.0.0.0:8080
  API:     http://0.0.0.0:8080/api/chat
  Health:  http://0.0.0.0:8080/health
  Project: /path/to/your-agent

​
Custom Port and Host

klisk serve --port 3000 --host 127.0.0.1

export PORT=3000
klisk serve

​
Serve Specific Project

klisk serve my-agent

​
Chat UI

The production server serves a built-in chat interface at the root URL: 
http://localhost:8080
Features:
  • Clean, responsive interface
  • Markdown rendering
  • Tool call inspection
  • File attachments (images, PDFs)
  • Real-time streaming
  • Conversation history

​
API Key Authentication

Protect your agent with API keys by setting environment variables:
.env
KLISK_API_KEY=sk-your-secret-key-here
You can set multiple keys by separating them with commas:
KLISK_API_KEY=sk-key-1,sk-key-2,sk-key-3

​
Supported Environment Variables

​
KLISK_API_KEY
string
Main API key for all endpoints
​
KLISK_CHAT_KEY
string
Alternative key specifically for chat endpoints
​
KLISK_WIDGET_KEY
string
Alternative key specifically for widget authentication
See REST API Authentication for usage details.

​
Health Check

The /health endpoint returns a simple status response: 
curl http://localhost:8080/health

{
  "status": "ok"
}
Use this for:
  • Container health checks
  • Load balancer probes
  • Uptime monitoring

​
Widget Embedding

Embed your agent as a chat widget on any website: 
<script src="http://localhost:8080/widget.js"></script>

​
Customization

Configure the widget appearance with data attributes: 
<script 
  src="https://your-agent.run.app/widget.js"
  data-position="bottom-right"
  data-color="#2563eb"
  data-width="380px"
  data-height="560px"
  data-key="your-api-key-here"
></script>
​
data-position
string
default:"bottom-right"
Widget position: bottom-right or bottom-left
​
data-color
string
default:"#2563eb"
Button background color (hex or CSS color)
​
data-width
string
default:"380px"
Chat panel width
​
data-height
string
default:"560px"
Chat panel height
​
data-key
string
API key for authentication (if enabled)

​
Example: Custom Styled Widget

<!-- Dark purple widget on the left -->
<script 
  src="https://your-agent.run.app/widget.js"
  data-position="bottom-left"
  data-color="#7c3aed"
  data-width="420px"
  data-height="600px"
></script>

​
Environment Variables

The server loads .env from your project directory:
.env
# Model provider API keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...

# Server configuration
PORT=8080

# Optional: API authentication
KLISK_API_KEY=sk-your-secret-key
Never commit .env files to version control. Add .env to your .gitignore.

​
Production Deployment

​
Docker

Create a Dockerfile: 
FROM python:3.12-slim

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

EXPOSE 8080

CMD ["klisk", "serve", ".", "--port", "8080"]
Build and run: 
docker build -t my-agent .
docker run -p 8080:8080 --env-file .env my-agent

​
Cloud Run

See the Cloud Run deployment guide for one-command deployment to Google Cloud.

​
Server Architecture

The production server (src/klisk/server/production.py:40-141):
  1. Loads your project configuration
  2. Discovers all agents and tools
  3. Creates a FastAPI app with CORS enabled
  4. Serves the chat UI static files
  5. Exposes API endpoints
  6. Runs with Uvicorn
Unlike klisk dev, the production server does not include:
  • File watching / hot reload
  • Studio UI
  • Agent editing endpoints
This reduces resource usage and attack surface for production deployments.

​
Troubleshooting

​
Port Already in Use

klisk serve --port 8081
Or kill the process using the port: 
lsof -ti:8080 | xargs kill -9

​
API Keys Not Working

Ensure your .env file is in the project directory: 
ls -la .env
cat .env  # Verify KLISK_API_KEY is set

​
No Agents Loaded

Run klisk check to validate your project: 
klisk check
Common issues:
  • Missing klisk.config.yaml
  • Agent definition errors
  • Tool import failures

​
Next Steps

REST API

Integrate your agent via HTTP

Deploy to Cloud Run

One-command deployment to production

Build docs developers (and LLMs) love

Get started for freeTalk to us