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

> Embed DeepSeek-TUI into your IDE using the HTTP runtime API. Stream completions and manage tool usage seamlessly without the terminal. Explore the power of DeepSeek-TUI integration.

- Repository: [DeepSeek/awesome-deepseek-agent](https://github.com/deepseek-ai/awesome-deepseek-agent)
- Tags: how-to-guide
- Published: 2026-08-15

---

**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](https://github.com/deepseek-ai/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:

```bash
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:

```javascript
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`:

```javascript
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:

```javascript
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:

```javascript
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:

```bash
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](https://github.com/deepseek-ai/awesome-deepseek-agent) repository for detailed specifications:

- **[`docs/deepseek-tui.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/deepseek-tui.md)**: Primary integration guide covering HTTP server setup, authentication, and endpoint descriptions.
- **[`docs/deepseek-tui.zh-CN.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/docs/deepseek-tui.zh-CN.md)**: Chinese language version of the integration documentation.
- **[`README.md`](https://github.com/deepseek-ai/awesome-deepseek-agent/blob/main/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](https://github.com/Hmbown/DeepSeek-TUI/blob/main/docs/RUNTIME_API.md) 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.