Skip to content
Newquantumcoderxyz v2 is now available

Server

Interact with quantumcoderxyz server over HTTP.

The quantumcoderxyz serve command runs a headless HTTP server that exposes an OpenAPI endpoint that an quantumcoderxyz client can use.


Usage

Terminal window
quantumcoderxyz serve [--port <number>] [--hostname <string>] [--cors <origin>]

Options

Flag Description Default
--port Port to listen on 4096
--hostname Hostname to listen on 127.0.0.1
--mdns Enable mDNS discovery false
--mdns-domain Custom domain name for mDNS service quantumcoderxyz.local
--cors Additional browser origins to allow []

--cors can be passed multiple times:

Terminal window
quantumcoderxyz serve --cors http://localhost:5173 --cors https://app.example.com

Authentication

Set quantumcoderxyz_SERVER_PASSWORD to protect the server with HTTP basic auth. The username defaults to quantumcoderxyz, or set quantumcoderxyz_SERVER_USERNAME to override it. This applies to both quantumcoderxyz serve and quantumcoderxyz web.

Terminal window
quantumcoderxyz_SERVER_PASSWORD=your-password quantumcoderxyz serve

How it works

When you run quantumcoderxyz it starts a TUI and a server. Where the TUI is the client that talks to the server. The server exposes an OpenAPI 3.1 spec endpoint. This endpoint is also used to generate an SDK.

This architecture lets quantumcoderxyz support multiple clients and allows you to interact with quantumcoderxyz programmatically.

You can run quantumcoderxyz serve to start a standalone server. If you have the quantumcoderxyz TUI running, quantumcoderxyz serve will start a new server.


Connect to an existing server

When you start the TUI it randomly assigns a port and hostname. You can instead pass in the --hostname and --port flags. Then use this to connect to its server.

The /tui endpoint can be used to drive the TUI through the server. For example, you can prefill or run a prompt. This setup is used by the quantumcoderxyz IDE plugins.


Spec

The server publishes an OpenAPI 3.1 spec that can be viewed at:

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

For example, http://localhost:4096/doc. Use the spec to generate clients or inspect request and response types. Or view it in a Swagger explorer.


APIs

The quantumcoderxyz server exposes the following APIs.


Global

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

Project

MethodPathDescriptionResponse
GET/projectList all projectsProject[]
GET/project/currentGet the current projectProject

Path & VCS

MethodPathDescriptionResponse
GET/pathGet the current pathPath
GET/vcsGet VCS info for the current projectVcsInfo

Instance

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

Config

MethodPathDescriptionResponse
GET/configGet config infoConfig
PATCH/configUpdate configConfig
GET/config/providersList providers and default models{ providers: Provider[], default: { [key: string]: string } }

Provider

MethodPathDescriptionResponse
GET/providerList all providers{ all: Provider[], default: {...}, connected: string[] }
GET/provider/authGet provider authentication methods{ [providerID: string]: ProviderAuthMethod[] }
POST/provider/{id}/oauth/authorizeAuthorize a provider using OAuthProviderAuthAuthorization
POST /provider/{id}/oauth/callback Handle OAuth callback for a provider boolean

Sessions

MethodPathDescriptionNotes
GET/sessionList all sessionsReturns Session[]
POST/sessionCreate a new sessionbody: { parentID?, title? }, returns Session
GET/session/statusGet session status for all sessionsReturns { [sessionID: string]: SessionStatus }
GET/session/:idGet session detailsReturns Session
DELETE /session/:id Delete a session and all its data Returns boolean
PATCH/session/:idUpdate session propertiesbody: { title? }, returns Session
GET/session/:id/childrenGet a session’s child sessionsReturns Session[]
GET/session/:id/todoGet the todo list for a sessionReturns Todo[]
POST /session/:id/init Analyze app and create AGENTS.md body: { messageID, providerID, modelID }, returns boolean
POST/session/:id/forkFork an existing session at a messagebody: { messageID? }, returns Session
POST /session/:id/abort Abort a running session Returns boolean
GET/session/:id/diffGet the diff for this sessionquery: messageID?, returns FileDiff[]
POST /session/:id/summarize Summarize the session body: { providerID, modelID }, returns boolean
POST /session/:id/revert Revert a message body: { messageID, partID? }, returns boolean
POST /session/:id/unrevert Restore all reverted messages Returns boolean
POST /session/:id/permissions/:permissionID Respond to a permission request body: { response, remember? }, returns boolean

Messages

MethodPathDescriptionNotes
GET/session/:id/messageList messages in a sessionquery: limit?, returns { info: Message, parts: Part[]}[]
POST/session/:id/messageSend a message and wait for responsebody: { messageID?, model?, agent?, noReply?, system?, tools?, parts }, returns { info: Message, parts: Part[]}
GET/session/:id/message/:messageIDGet message detailsReturns { info: Message, parts: Part[]}
POST /session/:id/prompt_async Send a message asynchronously (no wait) body: same as /session/:id/message, returns 204 No Content
POST/session/:id/commandExecute a slash commandbody: { messageID?, agent?, model?, command, arguments }, returns { info: Message, parts: Part[]}
POST/session/:id/shellRun a shell commandbody: { agent, model?, command }, returns { info: Message, parts: Part[]}

Commands

MethodPathDescriptionResponse
GET/commandList all commandsCommand[]

Files

MethodPathDescriptionResponse
GET/find?pattern=<pat>Search for text in filesArray of match objects with path, lines, line_number, absolute_offset, submatches
GET/find/file?query=<q>Find files and directories by namestring[] (paths)
GET/find/symbol?query=<q>Find workspace symbolsSymbol[]
GET/file?path=<path>List files and directoriesFileNode[]
GET/file/content?path=<p>Read a fileFileContent
GET/file/statusGet status for tracked filesFile[]

/find/file query parameters

  • query (required) — search string (fuzzy match)
  • type (optional) — limit results to "file" or "directory"
  • directory (optional) — override the project root for the search
  • limit (optional) — max results (1–200)
  • dirs (optional) — legacy flag ("false" returns only files)

Tools (Experimental)

MethodPathDescriptionResponse
GET/experimental/tool/idsList all tool IDsToolIDs
GET/experimental/tool?provider=<p>&model=<m>List tools with JSON schemas for a modelToolList

LSP, Formatters & MCP

MethodPathDescriptionResponse
GET/lspGet LSP server statusLSPStatus[]
GET/formatterGet formatter statusFormatterStatus[]
GET/mcpGet MCP server status{ [name: string]: MCPStatus }
POST /mcp Add MCP server dynamically body: { name, config }, returns MCP status object

Agents

MethodPathDescriptionResponse
GET/agentList all available agentsAgent[]

Logging

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

TUI

Method Path Description Response
POST /tui/append-prompt Append text to the prompt boolean
POST /tui/open-help Open the help dialog boolean
POST /tui/open-sessions Open the session selector boolean
POST /tui/open-themes Open the theme selector boolean
POST /tui/open-models Open the model selector boolean
POST /tui/submit-prompt Submit the current prompt boolean
POST /tui/clear-prompt Clear the prompt boolean
POST /tui/execute-command Execute a command ({ command }) boolean
POST /tui/show-toast Show toast ({ title?, message, variant }) boolean
GET /tui/control/next Wait for the next control request Control request object
POST /tui/control/response Respond to a control request ({ body }) boolean

Auth

Method Path Description Response
PUT /auth/:id Set authentication credentials. Body must match provider schema boolean

Events

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

Docs

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