How to Configure ds4-agent for Local Development: A Complete Setup Guide

To configure ds4-agent for local development, compile the binary with make ds4-agent, create a .env file specifying DS4_MODEL_PATH and DS4_AGENT_PORT, and run the executable to expose a local API endpoint that mirrors the hosted Instagit service.

The ds4-agent is the native coding agent shipped with the antirez/ds4 repository, providing a lightweight local server that implements the same API expected by Instagit clients. When you configure ds4-agent for local development, you enable your workstation to handle coding-agent requests using local model files instead of remote services. This setup requires building the C binary from source, defining environment variables parsed by the parse_env() function in ds4_agent.c, and starting the HTTP server to accept client connections.

Build the Agent from Source

The ds4-agent binary is compiled from ds4_agent.c using the Makefile provided in the repository root. This implementation provides a lightweight HTTP server capable of loading machine learning models and exposing the coding-agent API on your workstation.

git clone https://github.com/antirez/ds4.git
cd ds4
make ds4-agent

The Makefile contains the ds4-agent target which compiles ds4_agent.c into the executable. Ensure you have build-essential and cmake installed on Ubuntu systems before running the build command. For additional build options, refer to AGENT.md in the repository root.

Create a Local Configuration

The agent reads settings through a priority system: command-line flags override environment variables, which override hard-coded defaults. For local development, create a .env file in the repository root to store persistent settings.

Environment Variables vs. Command-Line Flags

According to the source code in ds4_agent.c, the parse_env() function extracts configuration from environment variables, looking for a file named .env in the current working directory:

DS4_AGENT_PORT=8080
DS4_MODEL_PATH=./models/ggml-model.bin
DS4_AUTH_TOKEN=localdev-token
DS4_LOG_LEVEL=debug

Override any value at runtime using command-line flags:

./ds4-agent --port 8081 --model ./models/ggml-model.bin

Required and Optional Configuration Keys

The agent recognizes these specific variables defined in the parsing logic:

• DS4_MODEL_PATH: Absolute or relative path to the compiled model file (GGML, ONNX, etc.). This is required and has no default value.
• DS4_AGENT_PORT: TCP port for the HTTP server. Defaults to 8000.
• DS4_AUTH_TOKEN: Secret token that Instagit clients must present. Leave empty for unauthenticated local testing.
• DS4_LOG_LEVEL: Verbosity level (debug, info, warn, error). Defaults to info.
• DS4_DB_PATH: Optional path to a SQLite KV-store for caching embeddings. Defaults to ./ds4_kvstore.db.

Create a .env file in the repository root with your development values. The repository already includes .env.example as a template and .gitignore to prevent committing credentials.

Run the Agent and Verify Connectivity

Before starting the server, ensure your model file exists. The repository includes download_model.sh to fetch compatible models:

./download_model.sh
./ds4-agent

When the server starts, you should see a log entry indicating the listening address. Verify the installation by querying the health endpoint implemented in the HTTP server:

curl http://127.0.0.1:8080/health

The expected output {"status":"ok"} confirms that ds4_agent.c has successfully initialized and is ready to accept requests using the schema defined in ds4_web.c.

Connect Your Client to the Local Endpoint

Configure your Instagit client to route requests to your local agent instead of the hosted service:

{
  "api_base": "http://127.0.0.1:8080",
  "api_key": "localdev-token"
}

The client will now send coding-agent requests to your local instance, processing them through the model specified in your DS4_MODEL_PATH.

Summary

• Compile the agent using make ds4-agent from the antirez/ds4 repository source, which builds ds4_agent.c into the executable binary.
• Configure via a .env file using variables like DS4_MODEL_PATH and DS4_AGENT_PORT, parsed by the parse_env() function in ds4_agent.c.
• Authenticate optionally using DS4_AUTH_TOKEN for secure local testing, or leave empty for unrestricted development access.
• Verify the setup by checking the /health endpoint before connecting your Instagit client to http://127.0.0.1:8080.

Frequently Asked Questions

What dependencies are required to build ds4-agent?

You need a standard C compiler toolchain including build-essential and cmake on Linux systems. The Makefile handles the compilation of ds4_agent.c and links against the core ds4 library implemented in ds4.c and ds4.h.

Can I run ds4-agent without authentication?

Yes. While you can set DS4_AUTH_TOKEN to test secure workflows, leaving it empty disables authentication entirely. This is suitable for local development but should not be used when exposing the agent to external networks.

How do I specify a different model file at runtime?

Use the --model command-line flag to override the DS4_MODEL_PATH environment variable. For example: ./ds4-agent --model ./models/custom-ggml.bin. The agent loads the model file during initialization and will fail to start if the path is invalid.

Why does the agent fail to start with "model not found"?

The DS4_MODEL_PATH variable is required and must point to an existing GGML or ONNX model file. Run download_model.sh to fetch a compatible model, or verify that your custom model path is correct relative to the working directory where you execute ds4-agent.

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