Server

kodine serve launches a headless HTTP server exposing an OpenAPI endpoint that any kodine client can talk to.

---

Usage

kodine serve [--port <number>] [--hostname <string>] [--cors <origin>]

Options

Flag	Description	Default
--port	Listening port	4096
--hostname	Listening hostname	127.0.0.1
--mdns	Turn on mDNS discovery	false
--mdns-domain	Custom mDNS domain name	kodine.local
--cors	Extra browser origins to allow	[]

Pass --cors more than once to allow several origins:

kodine serve --cors http://localhost:5173 --cors https://app.example.com

---

Authentication

Protect the server with HTTP basic auth by setting KODINE_SERVER_PASSWORD. The username is kodine unless you override it with KODINE_SERVER_USERNAME. Both kodine serve and kodine web honor this.

KODINE_SERVER_PASSWORD=your-password kodine serve

---

How it works

Running kodine launches two things: a TUI and a server, where the TUI acts as the client talking to that server. The server publishes an OpenAPI 3.1 spec endpoint, which is also what the SDK is generated from.

Tip

Reach for the kodine server whenever you want to drive kodine programmatically.

Thanks to this architecture, kodine can serve multiple clients at once and be driven entirely from code.

Use kodine serve when you want a standalone server. Even with the kodine TUI already running, kodine serve spins up a separate, new server.

---

Connect to an existing server

The TUI normally picks a random port and hostname on startup. Pass the --hostname and --port flags to fix them, then point your client at that address.

Through the /tui endpoint you can drive the TUI via the server — prefilling or running a prompt, for instance. The Kodine IDE plugins rely on exactly this setup.

---

Spec

An OpenAPI 3.1 spec is published by the server at:

http://<hostname>:<port>/doc

For instance, http://localhost:4096/doc. Generate clients from the spec, inspect request and response types, or browse it in a Swagger explorer.

---

APIs

These are the APIs the kodine server exposes.

---

Global

Method	Path	Description	Response
GET	/global/health	Server health and version	{ healthy: true, version: string }
GET	/global/event	Global events (SSE stream)	Event stream

---

Project

Method	Path	Description	Response
GET	/project	List every project	Project[]
GET	/project/current	Fetch the current project	Project

---

Path & VCS

Method	Path	Description	Response
GET	/path	Fetch the current path	Path
GET	/vcs	VCS info for the current project	VcsInfo

---

Instance

Method	Path	Description	Response
POST	/instance/dispose	Dispose of the current instance	boolean

---

Config

Method	Path	Description	Response
GET	/config	Read config info	Config
PATCH	/config	Update the config	Config
GET	/config/providers	List providers and their default models	{ providers: Provider[], default: { [key: string]: string } }

---

Provider

Method	Path	Description	Response
GET	/provider	List every provider	{ all: Provider[], default: {...}, connected: string[] }
GET	/provider/auth	Authentication methods per provider	{ [providerID: string]: ProviderAuthMethod[] }
POST	/provider/{id}/oauth/authorize	Start OAuth authorization for a provider	ProviderAuthAuthorization
POST	/provider/{id}/oauth/callback	Handle a provider’s OAuth callback	boolean

---

Sessions

Method	Path	Description	Notes
GET	/session	List every session	Returns Session[]
POST	/session	Create a session	body: { parentID?, title? }, returns Session
GET	/session/status	Status of every session	Returns { [sessionID: string]: SessionStatus }
GET	/session/:id	Session details	Returns Session
DELETE	/session/:id	Delete a session and its data	Returns boolean
PATCH	/session/:id	Modify session properties	body: { title? }, returns Session
GET	/session/:id/children	Child sessions of a session	Returns Session[]
GET	/session/:id/todo	A session’s todo list	Returns Todo[]
POST	/session/:id/init	Analyze the app and generate AGENTS.md	body: { messageID, providerID, modelID }, returns boolean
POST	/session/:id/fork	Fork a session at a given message	body: { messageID? }, returns Session
POST	/session/:id/abort	Abort an active session	Returns boolean
POST	/session/:id/share	Share the session	Returns Session
DELETE	/session/:id/share	Stop sharing the session	Returns Session
GET	/session/:id/diff	The session’s diff	query: messageID?, returns FileDiff[]
POST	/session/:id/summarize	Summarize a session	body: { providerID, modelID }, returns boolean
POST	/session/:id/revert	Roll back a message	body: { messageID, partID? }, returns boolean
POST	/session/:id/unrevert	Restore every reverted message	Returns boolean
POST	/session/:id/permissions/:permissionID	Answer a permission request	body: { response, remember? }, returns boolean

---

Messages

Method	Path	Description	Notes
GET	/session/:id/message	List a session’s messages	query: limit?, returns { info: Message, parts: Part[]}[]
POST	/session/:id/message	Send a message, waiting for the response	body: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, returns { info: Message, parts: Part[]}
GET	/session/:id/message/:messageID	Message details	Returns { info: Message, parts: Part[]}
POST	/session/:id/prompt_async	Send a message without waiting for the response	body: same as /session/:id/message, returns 204 No Content
POST	/session/:id/command	Run a slash command	body: { messageID?, agent?, model?, command, arguments }, returns { info: Message, parts: Part[]}
POST	/session/:id/shell	Execute a shell command	body: { agent, model?, command }, returns { info: Message, parts: Part[]}

---

Commands

Method	Path	Description	Response
GET	/command	List every command	Command[]

---

Files

Method	Path	Description	Response
GET	/find?pattern=<pat>	Search file contents	Array of match objects containing path, lines, line_number, absolute_offset, submatches
GET	/find/file?query=<q>	Locate files and directories by name	string[] (paths)
GET	/find/symbol?query=<q>	Locate workspace symbols	Symbol[]
GET	/file?path=<path>	Enumerate files and directories	FileNode[]
GET	/file/content?path=<p>	Read file contents	FileContent
GET	/file/status	Status of tracked files	File[]

/find/file query parameters

• query (required) — search string (fuzzy matched)
• type (optional) — restrict results to "file" or "directory"
• directory (optional) — search outside the project root
• limit (optional) — maximum results (1–200)
• dirs (optional) — legacy flag (pass "false" to get files only)

---

Tools (Experimental)

Method	Path	Description	Response
GET	/experimental/tool/ids	List every tool ID	ToolIDs
GET	/experimental/tool?provider=<p>&model=<m>	List tools plus JSON schemas for a model	ToolList

---

LSP, Formatters & MCP

Method	Path	Description	Response
GET	/lsp	LSP server status	LSPStatus[]
GET	/formatter	Formatter status	FormatterStatus[]
GET	/mcp	MCP server status	{ [name: string]: MCPStatus }
POST	/mcp	Dynamically add an MCP server	body: { name, config }, returns MCP status object

---

Agents

Method	Path	Description	Response
GET	/agent	List every available agent	Agent[]

---

Logging

Method	Path	Description	Response
POST	/log	Emit a log entry. Body: { service, level, message, extra? }	boolean

---

TUI

Method	Path	Description	Response
POST	/tui/append-prompt	Add text to the prompt	boolean
POST	/tui/open-help	Show the help dialog	boolean
POST	/tui/open-sessions	Show the session selector	boolean
POST	/tui/open-themes	Show the theme selector	boolean
POST	/tui/open-models	Show the model selector	boolean
POST	/tui/submit-prompt	Submit the prompt	boolean
POST	/tui/clear-prompt	Empty the prompt	boolean
POST	/tui/execute-command	Run a command ({ command })	boolean
POST	/tui/show-toast	Display a toast ({ title?, message, variant })	boolean
GET	/tui/control/next	Block until the next control request	Control request object
POST	/tui/control/response	Answer a control request ({ body })	boolean

---

Auth

Method	Path	Description	Response
PUT	/auth/:id	Store authentication credentials. The body must match the provider schema	boolean

---

Events

Method	Path	Description	Response
GET	/event	Server-sent events stream. Opens with server.connected, then bus events	Server-sent events stream

---

Docs

Method	Path	Description	Response
GET	/doc	The OpenAPI 3.1 specification	HTML page with OpenAPI spec