How to Use the Native ds4‑Agent Mode and Its Advantages Over the Server

The native ds4‑agent is a standalone, single‑process DeepSeek inference client that bypasses HTTP networking entirely, offering lower latency, stronger privacy, and built‑in tool integration compared to the ds4‑server HTTP API.

The native ds4‑agent mode in antirez/ds4 provides a lightweight, terminal‑based interface for running DeepSeek V4 inference locally. Unlike the ds4‑server HTTP API, the agent operates as a self‑contained binary with no network exposure, making it ideal for development workflows, sensitive data processing, and edge deployments. This guide explains how to run the agent, configure its options, and why you might prefer it over the server architecture.

Building and Running ds4‑agent

The agent is compiled alongside other DS4 binaries from the repository root.

Build Requirements

# Requires clang/clang‑llvm and a backend: Metal (macOS), CUDA (Linux), or CPU

make  # produces ds4, ds4‑agent, ds4‑server, etc.

Starting the Interactive Agent

./ds4-agent [options]

Core options parsed in ds4_agent.c (parse_options, lines 45‑48):

Option	Purpose
-m <model.gguf>	Model path (default: ds4flash.gguf)
--backend metal|cuda|cpu	Execution backend
--ssd-streaming	On‑demand layer loading for large models
-c <tokens>	Context window size
-n <tokens>	Maximum generation length
--temp <float>	Sampling temperature (default 0.8)
--non-interactive -p "<prompt>"	Single‑shot execution without REPL
--power <1‑100>	GPU power limit
--trace <file>	Detailed execution log

Interactive REPL Example

$ ./ds4-agent --backend metal -c 16384 -n 1024
> Write a Python script that lists files in the current directory.

The agent streams tokens directly to your terminal with sub‑millisecond overhead—no HTTP serialization or socket I/O involved.

Native Tool Integration

The agent embeds DSML/GLM tool schemas directly into its system prompt construction. Function agent_build_dsml_tools_prompt and agent_build_glm_tools_prompt (in ds4_agent.c) assemble native capabilities for file operations, bash execution, and web search.

Inline Tool Invocation Example

User: Create a file named hello.py with a print statement.

<｜DSML｜tool_calls>
<｜DSML｜invoke name="write">
<｜DSML｜parameter name="path" string="true">hello.py</｜DSML｜parameter>
<｜DSML｜parameter name="content" string="true">print("Hello from ds4-agent")</｜DSML｜parameter>
</｜DSML｜invoke>
</｜DSML｜tool_calls>

Tools execute in the same process—no external HTTP round‑trips required. The agent parses responses via its dedicated UI thread while a worker thread manages the DS4 session and KV cache.

Session Persistence and Checkpoints

The native ds4‑agent supports durable sessions through KV cache checkpointing.

Saving State

User: /save my_checkpoint

This triggers agent_worker_save (~line 600 in ds4_agent.c), serializing the KV cache to my_checkpoint.ds4. Restart with:

./ds4-agent --checkpoint my_checkpoint.ds4

Session continuity is handled internally; the server mode provides no equivalent without custom middleware.

Advantages of Native ds4‑agent Over ds4‑server

Dimension	ds4‑agent (native)	ds4‑server (HTTP API)
Latency	Direct in‑process calls eliminate network overhead	TCP + HTTP parsing adds milliseconds per request
Privacy	Zero network exposure; data never leaves localhost	Traffic traverses network stack even on 127.0.0.1
Resource Efficiency	Single process, no worker pools	Spawns threads/processes per connection
Tool Integration	Built‑in DSML/GLM schemas auto‑injected	Requires separate endpoint implementation
Debugging	--trace captures full internal state	Needs request‑ID correlation across processes
Offline Operation	Fully functional without connectivity	Assumes reachable client infrastructure
Session State	Native checkpoint/restore commands	Stateless by design; persistence is external

When to Choose Each Mode

• ds4‑agent: Local development, sensitive data, edge devices, interactive coding assistants, or any scenario where millisecond‑level latency matters.

• ds4‑server: Multi‑client deployments, service mesh integration, or when you need language‑agnostic HTTP access.

Non‑Interactive Batch Usage

Run one‑off prompts without entering the REPL:

./ds4-agent --non-interactive \
    -p "Summarize the README.md file" \
    --trace debug.log \
    -m ds4flash.gguf

Output streams to stdout; diagnostic data lands in debug.log. This pattern suits shell scripts and CI pipelines where you want deepseek inference without managing a daemon process.

SSD‑Streaming for Large Models

Enable on‑demand layer loading when working with models that exceed GPU VRAM:

./ds4-agent -m 70B_model.gguf \
    --ssd-streaming \
    -c 200000 \
    -n 1024 \
    --backend metal

The agent loads layers from disk as needed rather than pre‑allocating full model weights. See ds4_agent.c initialization logic for the --ssd-streaming flag handling.

Summary

• ds4‑agent runs DeepSeek V4 as a single, self‑contained process with no HTTP layer
• Lower latency, zero network exposure, and built‑in tools make it ideal for local workflows
• Session checkpointing via /save and /compact commands enables long‑running agent sessions
• Non‑interactive mode supports scripting and automation pipelines
• Source implementation lives in ds4_agent.c with worker threading and tool prompt construction in agent_build_dsml_tools_prompt/agent_build_glm_tools_prompt

Frequently Asked Questions

What is the main difference between ds4‑agent and ds4‑server?

The ds4‑agent is a terminal‑native, single‑process client that interacts directly with the DeepSeek inference engine. The ds4‑server exposes an HTTP API for remote clients. The agent avoids all network overhead and keeps data strictly local; the server adds flexibility for distributed access at the cost of latency and complexity.

Can ds4‑agent run without internet access?

Yes. The native ds4‑agent mode requires no network connectivity whatever. Model weights load from local GGUF files, inference runs on‑device, and tool execution (file reads, bash commands) operates against your local filesystem. This makes it suitable for air‑gapped or edge environments.

How do I resume a previous ds4‑agent session?

Use the checkpoint system. During a REPL session, type /save <filename> to persist the KV cache to disk. On restart, pass --checkpoint <filename> to restore context without re‑processing prior prompts. The agent_worker_save function in ds4_agent.c handles serialization.

Is ds4‑agent suitable for production API deployments?

Generally no. The ds4‑agent is optimized for single‑user, interactive workflows. For concurrent clients, load balancing, or service discovery, use ds4‑server with its HTTP API and horizontal scaling capabilities. The agent's architecture assumes one terminal session per process.

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