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

> Discover the native ds4-agent mode for DeepSeek inference. Bypass HTTP for lower latency, enhanced privacy, and integrated tools. Learn its advantages over the ds4-server.

- Repository: [Salvatore Sanfilippo/ds4](https://github.com/antirez/ds4)
- Tags: how-to-guide
- Published: 2026-08-05

---

**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

```bash

# 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

```bash
./ds4-agent [options]

```

Core options parsed in [`ds4_agent.c`](https://github.com/antirez/ds4/blob/main/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

```bash
$ ./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`](https://github.com/antirez/ds4/blob/main/ds4_agent.c)) assemble native capabilities for file operations, bash execution, and web search.

### Inline Tool Invocation Example

```text
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

```text
User: /save my_checkpoint

```

This triggers `agent_worker_save` (~line 600 in [`ds4_agent.c`](https://github.com/antirez/ds4/blob/main/ds4_agent.c)), serializing the KV cache to `my_checkpoint.ds4`. Restart with:

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

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

```bash
./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`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/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.