Server Mode
Interact with TF Code over HTTP using the headless server.
Usage
tfcode serve [--port <number>] [--hostname <string>] [--cors <origin>]
| Flag | Description | Default |
|---|---|---|
--port | Port to listen on | 0 (tries 4096) |
--hostname | Hostname to listen on | 127.0.0.1 |
--mdns | Enable mDNS discovery | false |
--mdns-domain | Custom domain name for mDNS | tfcode.local |
--cors | Additional browser origins | [] |
Authentication
Set TFCODE_SERVER_PASSWORD for HTTP basic auth (username defaults to tfcode):
TFCODE_SERVER_PASSWORD=your-password tfcode serve
How It Works
When you start TF Code normally, it runs both a TUI and a server internally. The TUI is the client. The server exposes an OpenAPI 3.1 spec that also generates the JavaScript SDK.
Run tfcode serve for a standalone server, or tfcode web to start the server and open the web interface. Use tfcode attach http://localhost:4096 to connect a TUI to a running server.
OpenAPI Spec
http://<hostname>:<port>/doc
API Reference
Global
| Method | Path | Description |
|---|---|---|
GET | /global/health | Get server health and version |
GET | /global/event | Get global events (SSE stream) |
Project
| Method | Path | Description |
|---|---|---|
GET | /project | List all projects |
GET | /project/current | Get current project |
Config
| Method | Path | Description |
|---|---|---|
GET | /config | Get config info |
PATCH | /config | Update config |
GET | /config/providers | List providers and default models |
Provider
| Method | Path | Description |
|---|---|---|
GET | /provider | List all providers |
GET | /provider/auth | Get provider authentication methods |
POST | /provider/{id}/oauth/authorize | Authorize a provider using OAuth |
POST | /provider/{id}/oauth/callback | Handle OAuth callback for a provider |
Sessions
| Method | Path | Description |
|---|---|---|
GET | /session | List all sessions |
POST | /session | Create a new session |
GET | /session/status | Get session status |
GET | /session/:id | Get session details |
DELETE | /session/:id | Delete a session |
PATCH | /session/:id | Update session |
POST | /session/:id/abort | Abort a running session |
POST | /session/:id/share | Share a session |
DELETE | /session/:id/share | Unshare a session |
GET | /session/:id/diff | Get the diff for this session |
POST | /session/:id/revert | Revert a message |
POST | /session/:id/unrevert | Restore all reverted messages |
POST | /session/:id/permissions/:permissionID | Respond to a permission request |
Messages
| Method | Path | Description |
|---|---|---|
GET | /session/:id/message | List messages |
POST | /session/:id/message | Send a message and wait for response |
POST | /session/:id/prompt_async | Send a message asynchronously |
POST | /session/:id/command | Execute a slash command |
Files
| Method | Path | Description |
|---|---|---|
GET | /find?pattern=<pat> | Search for text in files |
GET | /find/file?query=<q> | Find files by name |
GET | /file?path=<path> | List files and directories |
GET | /file/content?path=<p> | Read a file |
MCP & Agents
| Method | Path | Description |
|---|---|---|
GET | /mcp | Get MCP server status |
POST | /mcp | Add MCP server dynamically |
GET | /agent | List all available agents |
GET | /skill | List all skills |
Events
| Method | Path | Description |
|---|---|---|
GET | /event | Server-sent events stream |
Docs
| Method | Path | Description |
|---|---|---|
GET | /doc | OpenAPI 3.1 specification (HTML) |