Run a local Kortix instance to build and test against, clone a project, and iterate from the CLI.

This guide is for building on Kortix — developing your own project (agents, connectors, skills, kortix.yaml) against a Kortix instance you control. You'll stand up a local instance to test against, clone a project onto your machine, and drive the whole loop from the terminal.

Contributing to the Kortix codebase itself? That's a different setup — see Local development, which runs this monorepo with pnpm dev. This guide is about developing your Kortix project, not the platform.

The two pieces

Developing with Kortix needs two things:

An instance — a running Kortix server your project targets. Either a local instance you run yourself (below), or a remote one (Kortix Cloud, or a shared team/self-host box) you connect to.
The CLI — how you clone, configure, and drive that instance from your terminal.

1. Install the CLI

curl -fsSL https://kortix.com/install | KORTIX_CHANNEL=dev bash

KORTIX_CHANNEL selects which CLI build you get. It defaults to prod (the latest tagged release). Pass dev when you're developing against the dev channel or a self-host instance tracking dev/latest, so your CLI matches the features and API shape of the build you're testing against. Stick with the default prod when you're working against Kortix Cloud or a released version.

kortix --version      # confirm the install + channel
kortix --help         # full command index

2. Run a local instance to test against

kortix self-host isn't only for production VPS deployments — it's also the standard way to run Kortix locally. It starts the full stack (frontend, API, LLM gateway, and the bundled Supabase) as one Docker Compose project on your machine, giving you a real Kortix server to point your project at and iterate against — no cloud account required.

For a production deployment on a VPS with a public domain, follow Self-hosting. The steps below are the local development path: same stack, no domain, reachable from your machine.

Start it

On a local machine with no public domain, use a Cloudflare tunnel for reachability — init sets everything else to sensible defaults:

kortix self-host init --tunnel cloudflare
kortix self-host start

init is a short guided flow (pass --yes to accept defaults). To track the same build as the dev channel, add --version dev.

Check it's healthy

kortix self-host status      # containers, versions, drift, last update
kortix self-host logs        # tail logs
kortix self-host open        # open the dashboard in a browser

Point the CLI at it

Your self-host instance is the built-in selfhost host:

kortix hosts use selfhost
kortix hosts current         # → selfhost

Common lifecycle commands while developing:

Command	Does
`kortix self-host start`	Pull images and start the stack
`kortix self-host restart`	Restart the stack
`kortix self-host stop`	Stop it (data persists)
`kortix self-host update`	Pull + apply the configured channel/version
`kortix self-host status`	Container status, drift, last update
`kortix self-host logs [service]`	Tail logs
`kortix self-host doctor`	Validate Docker + Compose config

Prefer targeting a shared instance instead of running one locally? Skip this section and connect to it: kortix hosts add <name> --url <api-url> --login, then kortix hosts use <name>. Everything below works the same against any host.

3. Clone a project onto your machine

Clone through the authenticated Kortix git proxy. Tokens are never written into the URL or your Git config — Kortix resolves the current provider credential just in time, and your local clone stays the source of truth.

kortix projects ls                         # find the project id
kortix projects clone <project-id>         # clone via the Kortix proxy
cd <cloned-dir>
kortix init --force                        # (re)initialize local project config
kortix env pull                            # pull the project's secrets as a local .env

Kortix proxy origin. Sessions and the CLI use a single stable git URL; Kortix resolves the underlying provider credential at request time, so the real backing provider can change without you touching your local remote.

4. Iterate

With an instance running and a project cloned, drive the loop from the terminal:

# Point agents at models, connect providers
kortix agents model <agent> anthropic/claude-opus-4-8
kortix providers set openai <key>          # or: kortix providers login openai

# Start a session and talk to it
kortix sessions new --prompt "Build X" --wait
kortix chat

# Ship changes to the instance
kortix ship                                # push code + open a change request

# Debug model calls
kortix gateway test <model>
kortix gateway logs --failed               # add a logId for full upstream error detail

See Using the command line for the full command reference and the session-sandbox workflow.

The loop, end to end

# once
curl -fsSL https://kortix.com/install | KORTIX_CHANNEL=dev bash
kortix self-host init --tunnel cloudflare && kortix self-host start
kortix hosts use selfhost

# per project
kortix projects clone <project-id>
cd <dir> && kortix init --force && kortix env pull

# iterate
kortix sessions new --prompt "..." --wait
kortix chat
kortix ship

Next steps

Using the command line — the full CLI reference
Self-hosting — take the same stack to a production VPS
Managing secrets — how project secrets work
Local development — contributing to the Kortix platform itself

Developing with Kortix