How to Use the DeepSeek-TUI HTTP Runtime API for IDE Embedding

DeepSeek-TUI ships a built-in HTTP server that exposes a Codex-style /v1/* runtime API, allowing any IDE or external UI to create sessions, stream completions, and manage tool usage without launching the interactive terminal interface.

The DeepSeek-TUI HTTP runtime API converts the terminal-based assistant into a headless service perfect for IDE embedding. According to the awesome-deepseek-agent repository, this architecture lets external clients act as thin wrappers around the TUI's session management, model inference, and tool orchestration layers.

Architecture Overview

The runtime consists of four primary components:

• DeepSeek-TUI binary (deepseek): Runs the interactive TUI or starts the HTTP server via the serve --http command.
• HTTP Server: Listens on a configurable port (default 8080) and implements REST endpoints under /v1/* (e.g., /v1/completions, /v1/chat/completions). It forwards requests to the internal model runner and handles token limits, streaming, and tool execution.
• Model Backend: Communicates with the DeepSeek API (https://api.deepseek.com) using credentials from environment variables or config files. Supports model switching via DEEPSEEK_MODEL or DEEPSEEK_PROVIDER.
• MCP, Skills, and Hooks: Exposed through the same HTTP layer, allowing the IDE to invoke MCP commands, load custom skills, and trigger pre/post-execution hooks directly.

The server maintains the TUI's permission model (Plan → Agent → YOLO modes) and sandboxes all tool executions, requiring explicit client approval when YOLO mode is disabled.

Starting the HTTP Server

Launch the headless server from your terminal:

deepseek serve --http --port 8080

By default, the server binds to port 8080. You can customize the port with the --port flag or via environment configuration.

Authentication Configuration

The server requires a valid DeepSeek API key for model access. Provide credentials using one of these methods:

• Set the DEEPSEEK_API_KEY environment variable.
• Store the key in ~/.deepseek/config.toml.

The server reads these values on startup to authenticate requests to the DeepSeek API backend.

Session Management and Chat Completions

IDE embedding begins with session creation. Each session maintains conversation state and tool context across multiple requests.

Create a new session:

const fetch = require('node-fetch');

async function createSession() {
  const res = await fetch('http://localhost:8080/v1/sessions', { 
    method: 'POST' 
  });
  const data = await res.json();  // { session_id: "abc123", ... }
  return data.session_id;
}

Send a chat completion request using the acquired session_id:

async function chat(sessionId, prompt) {
  const response = await fetch('http://localhost:8080/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      session_id: sessionId,
      messages: [{ role: 'user', content: prompt }],
      mode: 'agent'  // Options: plan, agent, yolo
    })
  });
  const data = await response.json();
  return data.choices[0].message.content;
}

Include the mode parameter to specify the tool permission level: plan (suggest only), agent (ask before action), or yolo (execute automatically).

Streaming Responses with Server-Sent Events

For real-time token streaming that mimics the TUI experience, enable Server-Sent Events (SSE) by setting stream: true in your request:

async function streamChat(sessionId, prompt) {
  const response = await fetch('http://localhost:8080/v1/chat/completions', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      session_id: sessionId,
      messages: [{ role: 'user', content: prompt }],
      stream: true,
      mode: 'agent'
    })
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder('utf-8');
  
  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    
    const chunk = decoder.decode(value);
    const lines = chunk.split('\n').filter(l => l.startsWith('data:'));
    
    for (const line of lines) {
      const payload = JSON.parse(line.slice(5));
      process.stdout.write(payload.choices[0].delta.content);
    }
  }
}

Each SSE line is prefixed with data: and contains a JSON fragment with the incremental content in choices[0].delta.content.

Tool Usage and Approval Workflow

When the model invokes a tool, the server returns a tool_calls object in the response. If the session is not in YOLO mode, the IDE must explicitly approve the execution:

async function approveTool(sessionId, toolCallId) {
  await fetch(`http://localhost:8080/v1/tool_calls/${toolCallId}/approve`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ session_id: sessionId })
  });
}

This workflow mirrors the TUI's interactive approval system, ensuring that dangerous operations require explicit user consent even when running headlessly.

MCP Integration

The HTTP runtime exposes Model Context Protocol (MCP) endpoints for external tool integration. List available MCP servers or invoke specific commands directly from your IDE:

curl -X POST http://localhost:8080/v1/mcp/list

Use the /v1/mcp/* endpoints to dynamically add servers, list capabilities, or execute MCP commands without restarting the TUI server.

Key Implementation Files

Reference these files in the awesome-deepseek-agent repository for detailed specifications:

• docs/deepseek-tui.md: Primary integration guide covering HTTP server setup, authentication, and endpoint descriptions.
• docs/deepseek-tui.zh-CN.md: Chinese language version of the integration documentation.
• README.md: Project overview listing DeepSeek-TUI as a featured component with quick-start links.
• External Runtime Spec: The complete OpenAPI-style contract is defined in the DeepSeek-TUI Runtime API specification.

Summary

• DeepSeek-TUI provides a headless HTTP server via deepseek serve --http, exposing a /v1/* API compatible with IDE embedding.
• Session-based architecture requires creating a session_id via POST /v1/sessions before sending chat requests to POST /v1/chat/completions.
• Streaming support uses Server-Sent Events (stream: true) for real-time token delivery, essential for responsive IDE integrations.
• Tool safety follows the TUI's permission model; IDE clients must approve tool_calls via POST /v1/tool_calls/{id}/approve when not in YOLO mode.
• MCP endpoints (/v1/mcp/*) enable external tool integration without modifying the core TUI binary.

Frequently Asked Questions

What port does the DeepSeek-TUI HTTP server use by default?

The server listens on port 8080 by default. You can override this by passing the --port flag when starting the server (e.g., deepseek serve --http --port 3000).

How does authentication work for the HTTP runtime API?

The server reads the DEEPSEEK_API_KEY environment variable or the ~/.deepseek/config.toml configuration file to authenticate requests against the DeepSeek API backend. No additional API key is required for local HTTP client requests, but the upstream DeepSeek key must be valid.

Can I use the HTTP API without implementing the tool approval workflow?

Yes, by setting mode: 'yolo' in your chat completion requests, the server will automatically execute tool calls without returning approval prompts. However, for production IDE integrations, agent or plan modes are recommended to maintain security and transparency.

Does the HTTP server support the Model Context Protocol (MCP)?

Yes, the runtime exposes dedicated /v1/mcp/* endpoints that allow IDE clients to list, add, and invoke MCP servers. This enables integration with external tool ecosystems such as filesystem browsers, database clients, or version control systems directly through the DeepSeek-TUI HTTP layer.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}