DeepSeek Local API & CLI Client (deepseek-local-api)

Convert DeepSeek Web Chat into a zero-overhead, OpenAI-compatible local API server and interactive terminal CLI.

[!IMPORTANT]

🧠 Native Tool Calling Support (v0.9.0+)

• Zero-Config Tool / Function Calling: When agent harnesses like Hermes, Claude Code, or custom bots pass tools in their requests, the gateway automatically guides DeepSeek, parses tool calls (e.g. write_file, terminal), normalizes local filesystem paths, and streams standard OpenAI delta.tool_calls.
• The Hands (Your Agent Harness): The agent harness executes the returned tool calls locally and creates files, executes terminal commands, and edits code seamlessly.
• Install the Official Skill via skills.sh (Vercel):

  npx skills add m-elramsesy/deepseek-local-api --skill delegate-to-deepseek -g

  Registry: skills.sh/m-elramsesy/deepseek-local-api/delegate-to-deepseek

⚡ Quick Start

1. Set Your Token

Obtain your token from chat.deepseek.com:

1. Sign in to chat.deepseek.com.
2. Open DevTools (F12), go to Application > Local Storage.
3. Copy the value of userToken.
4. Create a .env file in your directory:

   DEEPSEEK_TOKEN="your_token_here"

2. Run Directly with npx

# Start the OpenAI-compatible local server on port 4040
npx @ramsesy/deepseek-local-api -s 4040

# Or launch interactive terminal chat
npx @ramsesy/deepseek-local-api

3. Or Install Globally

npm install -g @ramsesy/deepseek-local-api

# Start local server anywhere:
deepseek -s 4040

🧠 Official Agent Skill: delegate-to-deepseek (skills.sh)

MANDATORY FOR ANY HARNESS OR CODING AGENT When using this local API server with any agent harness (such as Hermes, Claude Code, OpenCode, Cursor, Continue, Antigravity), the agent must have the delegate-to-deepseek skill installed.

📥 One-Line Installation via Vercel's Skills CLI

# Install globally for all your AI agents:
npx skills add m-elramsesy/deepseek-local-api --skill delegate-to-deepseek -g

# Or install specifically for the current project:
npx skills add m-elramsesy/deepseek-local-api --skill delegate-to-deepseek

Skills Registry Listing: https://skills.sh/m-elramsesy/deepseek-local-api/delegate-to-deepseek

🔄 How the Delegation Protocol Works:

1. Context Packaging (Harness): Your agent gathers existing project files, error logs, or user requirements.
2. Text Request (Gateway): The agent calls http://localhost:4040/v1/chat/completions (or uses call-deepseek.js).
3. Deep Synthesis (DeepSeek): DeepSeek R1 / V3 reasons through the problem and generates 100% complete, un-truncated production code.
4. Tool Execution (Harness): Your agent receives the pure text, extracts the code, and uses its native tools (write_to_file, replace_file_content, run_command) to create the file on disk or Desktop, run tests, and execute commands.

🛠️ Usage Modes

Mode 1: OpenAI-Compatible Local Server

Run a local API server compatible with any OpenAI API client or agent harness:

# Start on localhost (127.0.0.1:4040)
deepseek --server 4040

# Expose to your local network / LAN (0.0.0.0:8080)
deepseek --server 8080 --network

Supported Endpoints:

• POST http://localhost:4040/v1/chat/completions
  • Supports standard OpenAI payload (model, messages, stream).
  • Supports both Streaming (stream: true via SSE) and Non-Streaming (stream: false).
  • Supports reasoning_content delta for R1 thinking process.
  • Automatic fallback to .env token if client sends placeholder/dummy keys.
  • Full CORS enabled.
• GET http://localhost:4040/v1/models
  • Returns deepseek-chat and deepseek-reasoner.
• GET http://localhost:4040/health
  • Health check endpoint.

Mode 2: Interactive Terminal Chat

Run without arguments to start an interactive multi-turn conversation:

deepseek

Interactive Features:

• Tab Autocomplete: Type / and press Tab to see and autocomplete commands.
• Arrow-Key Session Picker: Use ↑ / ↓ to select from past saved sessions.
• Live In-Chat Commands:
  • /help: Display all available commands.
  • /thinking: Toggle reasoning/thinking mode on or off.
  • /search: Toggle web search mode on or off.
  • /server [port]: Launch the local OpenAI-compatible server on the fly.
  • /new: Start a fresh session.
  • /id: Print current session ID and direct web URL.
  • /exit: Quit session.

Mode 3: Single-Turn CLI Prompt

Send a quick prompt and stream the result directly to your terminal:

deepseek "Explain the difference between process.nextTick and setImmediate in Node.js"

Mode 4: Agent Delegation & Direct File Output (call)

Offload heavy code generation directly from your terminal or AI Agent with automatic code extraction:

# Offload file creation to DeepSeek (saves tokens on Gemini/Claude/Hermes!)
deepseek call -p "Create an Express rate limiter middleware with in-memory sliding window" -o ./src/rateLimiter.js

# Or run anywhere via npx (zero installation needed):
npx @ramsesy/deepseek-local-api call -p "Write an async queue worker in TypeScript" -o ./src/queue.ts

# Refactor an existing file using DeepSeek R1 reasoning:
deepseek call -p "Optimize performance and fix memory leaks" -f ./src/dataProcessor.js -m deepseek-reasoner -o ./src/dataProcessor.js

💰 Token Economics: Frontier Models + DeepSeek Subagent

| Model in Your Harness | Challenge | Solution with deepseek-local-api | | :--- | :--- | :--- | | Gemini 2.5 (Antigravity) | High rate-limit & token consumption for 500+ line codebases | Gemini plans the architecture, DeepSeek writes the heavy code (0 tokens). | | Claude 3.7 / Opus (Claude Code) | Expensive output token pricing for large boilerplate files | Claude oversees & audits, DeepSeek generates the raw implementation. | | Hermes / OpenCode | Local / open-source tool execution efficiency | Harness executes write_to_file & tests, DeepSeek handles R1 reasoning. |

🤖 Harness Integration Guide (Hermes, OpenCode, Claude Code, Cursor)

Configure your harness to point to your local endpoint:

Configuration Settings

| Setting | Value | | :--- | :--- | | Base URL | http://localhost:4040/v1 | | API Key | dummy-token (any string; server uses your .env token) | | Models | deepseek-chat or deepseek-reasoner | | Streaming | Enabled (true) |

Bundled CLI Helper for Harnesses:

Harnesses can also directly query the gateway via the zero-dependency script:

node skills/delegate-to-deepseek/scripts/call-deepseek.js \
  --port 4040 \
  --prompt "Create a complete Node.js CLI script for rate-limiting"

📄 License

MIT