# How to Use the `--chdir` Option to Launch `ds4-agent` from a Different Directory

> Learn how to use the ds4-agent --chdir option to launch from a different directory. Easily change the working directory before loading model files or initializing the inference engine.

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

---

**Use `ds4-agent --chdir DIR` to change the working directory before the program loads model files or initializes its inference engine.**

The `ds4-agent` command-line client from the [antirez/ds4](https://github.com/antirez/ds4) repository provides a `--chdir` flag that executes a directory change immediately at startup. This eliminates the need to manually `cd` into target directories before launching the interactive agent, which is essential when models and configurations reside outside your current shell location.

## Where `--chdir` Is Implemented in the Source Code

### Command-Line Parsing in ds4_agent.c

The option is recognized during argument parsing in [`ds4_agent.c`](https://github.com/antirez/ds4/blob/main/ds4_agent.c). At approximately line 677, the parser stores the provided directory path in `c.chdir_path`:

```c
// From ds4_agent.c (~L677)
// --chdir DIR  Change working directory before loading assets

```

### Directory Change Execution

After `parse_options()` returns the populated configuration struct, `main()` checks for a non-NULL `cfg.chdir_path` and immediately executes `chdir()`:

```c
// From ds4_agent.c (~L11123-L11127)
if (cfg.chdir_path) {
    if (chdir(cfg.chdir_path) == -1) {
        fprintf(stderr, "Error changing directory: %s\n", strerror(errno));
        exit(1);
    }
}

```

If the `chdir()` call fails, the program prints an error message and exits with status 1. This ensures the agent never runs with an incorrect working directory.

## Practical Usage Examples

### Basic: Run Agent from a Sibling Directory

When your model files live in a separate folder from your launch location:

```bash

# Current directory: /home/user/tools

# Target model directory: /home/user/models/llama-7B

ds4-agent --chdir /home/user/models/llama-7B -m llama-7B.gguf

```

The agent behaves exactly as if you had executed `cd /home/user/models/llama-7B` first, then launched without `--chdir`.

### Combined with Backend and Thread Options

```bash
ds4-agent --chdir /mnt/data/models \
          --cuda \
          -m mixtral-8x7b-v0.1.gguf \
          -t 4

```

**Order of operations matters:** The directory change happens before any model loading, CUDA initialization, or thread pool creation. Relative paths passed to `-m` are resolved against the new working directory.

### Using `--chdir` with ds4-server

The server component implements identical behavior in [`ds4_server.c`](https://github.com/antirez/ds4/blob/main/ds4_server.c) (parsing at ~L12724, application at ~L12891):

```bash
ds4-server --chdir /opt/ds4/models --port 8080

```

## When `--chdir` Is Essential

- **Containerized deployments:** Launch from a read-only root filesystem while loading writable models from a mounted volume
- **CI/CD pipelines:** Execute from build directories while referencing standardized model paths
- **Shared environments:** Avoid polluting shell history with `cd` commands when switching between model versions
- **Relative path configurations:** When `ds4-agent` reads relative paths from config files, the working directory determines their resolution

## Error Handling Behavior

The implementation performs strict validation:

| Scenario | Result |
|----------|--------|
| Directory does not exist | Error message + exit code 1 |
| Permission denied | Error message + exit code 1 |
| Path is a file, not directory | Error message + exit code 1 |
| No `--chdir` provided | Normal startup from invocation directory |

As implemented in [`ds4_agent.c`](https://github.com/antirez/ds4/blob/main/ds4_agent.c), the error message includes the system `errno` description via `strerror()`.

## Summary

- **`--chdir DIR`** changes working directory before any asset loading or engine initialization
- Implementation spans `parse_options()` (~L677) and `main()` (~L11123) in [`ds4_agent.c`](https://github.com/antirez/ds4/blob/main/ds4_agent.c)
- Both `ds4-agent` and `ds4-server` support identical `--chdir` semantics
- Failed directory changes are fatal errors with descriptive messages and exit code 1
- Useful for containerized workflows, CI/CD, and managing relative-path configurations

## Frequently Asked Questions

### Does `--chdir` affect relative paths passed to `-m`?

Yes. The directory change occurs before model loading, so relative paths in `-m` are resolved against the new working directory. Absolute paths remain unaffected.

### Can I use `--chdir` with environment variables?

The shell expands variables before passing to `ds4-agent`. Use standard shell syntax: `ds4-agent --chdir "$MODEL_DIR" -m model.gguf`. The source code receives the expanded path directly.

### Is `--chdir` available in ds4-server?

Yes. [`ds4_server.c`](https://github.com/antirez/ds4/blob/main/ds4_server.c) implements identical parsing (~L12724) and execution (~L12891) logic. The flag works with both interactive client and HTTP server binaries.

### What happens if I specify a non-existent directory?

The program prints an error message including the system error description and exits with status 1. Execution stops before any model loading or initialization begins.