Configuration

klisk.config.yaml

Each project has a klisk.config.yaml file at its root with the project configuration.

name: my-agent
entry: src/main.py
studio:
  port: 3000
api:
  port: 8321
deploy:
  chat:
    enabled: true
    title: ""
    welcome_message: ""
    attachments: true
  widget:
    enabled: true
    color: "#2563eb"
    position: bottom-right
    width: 380px
    height: 560px
    welcome_message: ""
    placeholder: "Type a message..."
    auto_open: false
    user_message_color: "#2563eb"
    header_color: ""
    bubble_icon: "chat"
  api:
    cors_origins:
      - "*"

Fields

Field	Default	Description
name	"MyAgent"	Project display name
entry	"src/main.py"	Python entry point that defines the main agent

Studio

Field	Default	Description
studio.port	3000	Port for the Studio frontend

API

Field	Default	Description
api.port	8321	Port for the dev API server

Deploy

Settings that control the production server (klisk start). These can also be configured visually from the Studio's Customize section.

Chat page

Field	Default	Description
deploy.chat.enabled	true	Serve the chat UI at /
deploy.chat.title	""	Title shown in the chat header
deploy.chat.welcome_message	""	Message shown before the first user message
deploy.chat.attachments	true	Allow file attachments (images, PDFs)

Widget

Field	Default	Description
deploy.widget.enabled	true	Serve the embeddable widget at /widget.js
deploy.widget.color	"#2563eb"	Button and header color
deploy.widget.position	"bottom-right"	"bottom-right" or "bottom-left"
deploy.widget.width	"380px"	Chat panel width
deploy.widget.height	"560px"	Chat panel height
deploy.widget.welcome_message	""	Message shown when widget opens
deploy.widget.placeholder	"Type a message..."	Input placeholder text
deploy.widget.auto_open	false	Open widget automatically on page load
deploy.widget.user_message_color	"#2563eb"	Color of user message bubbles
deploy.widget.header_color	""	Custom header color (empty = use color)
deploy.widget.bubble_icon	"chat"	Icon for the floating button

API

Field	Default	Description
deploy.api.cors_origins	["*"]	Allowed CORS origins

.env

Environment variables file for API keys and sensitive configuration. It's auto-generated when creating a project and included in .gitignore.

# OpenAI (default)
OPENAI_API_KEY=sk-...

# Other providers
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
MISTRAL_API_KEY=...

requirements.txt

Python dependencies for the project. Always includes klisk as the first dependency.

klisk
httpx
pandas

To install dependencies in the project's virtual environment:

.venv/bin/pip install -r requirements.txt

Directory structure

~/klisk/                          # Root workspace
└── projects/                     # Projects directory
    ├── my-agent/                 # A project
    │   ├── klisk.config.yaml
    │   ├── .env
    │   ├── .gitignore
    │   ├── requirements.txt
    │   ├── .venv/
    │   ├── src/
    │   │   ├── __init__.py
    │   │   ├── main.py           # Entry point
    │   │   └── tools/
    │   │       ├── __init__.py
    │   │       └── ...           # Tools
    │   └── tests/
    └── another-agent/            # Another project
        └── ...

Virtual environment

Each project has its own .venv/ automatically created by klisk create. It's automatically activated when using Klisk commands (studio, run, start).

Editors like VS Code and PyCharm detect the .venv/ automatically to resolve imports like from klisk import define_agent.