Install and start Kontext Studio
Kontext Studio runs on your own machine. The local server, the data engine, and the web app all start together, and everything you create stays in a workspace directory on disk.
Before you start
Section titled “Before you start”You need Python 3.12–3.14; 3.15 is not yet supported. Install with uv,
pipx, or pip in a virtual environment.
Install uv if you prefer it.
The interpreter name matters: a bare python3 may point at a release outside
the supported range. Name the version when you create the environment.
| Platform | Create the environment |
|---|---|
| macOS / Linux | python3.13 -m venv .venv |
| Windows | py -3.13 -m venv .venv |
| uv | uv venv --python 3.13 |
Any of 3.12, 3.13, or 3.14 works. Check the result before installing:
python -c "import sys; print(sys.version)"uv tool install selects a supported interpreter for you, so it needs no
version argument.
Install
Section titled “Install”With uv (recommended)
Section titled “With uv (recommended)”uv tool install kontext-studioWith pipx
Section titled “With pipx”pipx install kontext-studioWith pip in a virtual environment
Section titled “With pip in a virtual environment”python3.13 -m venv .venvsource .venv/bin/activate # Windows: .venv\Scripts\activatepython -m pip install kontext-studioTo pin a specific release, add the version number to any install command:
uv tool install "kontext-studio==0.261.0"pipx install "kontext-studio==0.261.0"python -m pip install "kontext-studio==0.261.0"To upgrade later:
uv tool upgrade kontext-studiopipx upgrade kontext-studiopython -m pip install --upgrade kontext-studioPip installs into the active Python environment; use a virtual environment. If the server reports an unsupported SQLite version, use a Python build with SQLite 3.51.2 or newer, or uv’s managed Python.
Start the server
Section titled “Start the server”Run the server from the directory that should hold your workspace:
kontext serveThe first start creates a workspace in ~/.kontext/ and prints the URL to open.
Kontext seeds a placeholder profile called Local Admin and one project
called Local Project, so you can start working immediately. If the server
reports a missing launch token, a Host/Origin error, or a port conflict, see
local operations and troubleshooting.
To open the browser automatically:
kontext serve --openUse --host, --port, or --lake-path to bind a different address, change
the port, or keep the workspace somewhere other than .kontext/.
Replace the placeholder profile
Section titled “Replace the placeholder profile”The placeholder profile is enough to get started, but it is worth replacing
before you add data. The setup page is available at /setup on the same address
as the app, for example http://localhost:8000/setup.
- Kontext starts with a placeholder profile. Open
/setupbefore you add any data to replace it with your own name and email.
- Enter a first name, an optional last name, and an email address.

- Select Create local profile. Kontext stores the profile on this machine and signs you in.

- Kontext opens your workspace with one project and the local profile you created.

Connect a model provider
Section titled “Connect a model provider”Kontext Studio does not bundle a model. After signing in, open LLM Providers and add a local or cloud provider, then choose the default model for your work. See Connect a model provider for the supported providers and settings.
CLI commands
Section titled “CLI commands”Most work happens in the browser, but kontext-studio also exposes the local
workspace from the terminal:
| Command | Description |
|---|---|
kontext serve |
Start the local server and UI |
kontext project list |
List projects in the local workspace |
kontext project create <name> |
Create a project |
kontext project import <files…> |
Import data files into a project |
kontext job list |
List available job types |
kontext job run <type> |
Run a job synchronously |
project import accepts CSV, Parquet, JSON, and other data files. Pass
--project to target a project other than the first one, and --subdir to
choose where the files land under the project’s data directory.
Supported platforms
Section titled “Supported platforms”| Platform | Architecture |
|---|---|
| macOS | arm64, x86_64 |
| Linux | x86_64 |
| Windows | x86_64 |
Python 3.12–3.14 is required.