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

> Set up ds4-agent for local development. Compile the binary, configure your .env file, and run the agent to expose a local API for your coding needs.

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

---

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

```bash
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`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/ds4_agent.c), the `parse_env()` function extracts configuration from environment variables, looking for a file named `.env` in the current working directory:

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

```bash
./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`](https://github.com/antirez/ds4/blob/main/download_model.sh) to fetch compatible models:

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

```bash
curl http://127.0.0.1:8080/health

```

The expected output `{"status":"ok"}` confirms that [`ds4_agent.c`](https://github.com/antirez/ds4/blob/main/ds4_agent.c) has successfully initialized and is ready to accept requests using the schema defined in [`ds4_web.c`](https://github.com/antirez/ds4/blob/main/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:

```json
{
  "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`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/ds4_agent.c) and links against the core ds4 library implemented in [`ds4.c`](https://github.com/antirez/ds4/blob/main/ds4.c) and [`ds4.h`](https://github.com/antirez/ds4/blob/main/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`](https://github.com/antirez/ds4/blob/main/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`.