> ## Documentation index
> Fetch the complete documentation index at: https://haarness.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Start a Haarness server

A Haarness server runs the agent for one project folder and exposes it over HTTP. Start one when
you want to drive Haarness from a script, the [SDKs](https://haarness.ai/docs/server/sdks.md), an
[editor](https://haarness.ai/docs/server/acp.md) or another machine.

You do not need this for everyday use: `haarness`, `haarness tui` and `haarness run` already start
a private server for the folder in the background.

## Start a server

From the project folder:

```sh
cd ~/code/my-project
haarness serve
```

You will see:

```text
Haarness server listening on http://127.0.0.1:4096
```

Check it from another terminal:

```sh
curl http://127.0.0.1:4096/v1/info
```

The reply names the project folder in `workspace` and the default model in `defaultProvider` and
`defaultModel`. The server keeps running until you press Ctrl-C or stop it.

If another program already holds port 4096, the server takes a free port and says so; use the
address it prints. `--port 5000` asks for a port that must be free, and `--port 0` always picks a
free one.

By default the server listens on `127.0.0.1` only and asks for no password. Anything running on
your computer as any user can reach it. Read [Connect safely](https://haarness.ai/docs/server/authentication.md) before
you change that.

## Run it in the background

```sh
haarness serve --daemon     # start, or reuse the one already running
haarness serve --stop       # stop it
```

`--daemon` prints the server's process id and address, then returns. Both commands act on the
server for the current folder; add `--workspace PATH` to pick another.

## Connect a client to it

| Client | How |
| --- | --- |
| Terminal UI | `haarness attach http://127.0.0.1:4096` |
| One prompt | `haarness run --attach http://127.0.0.1:4096 "…"` |
| Desktop | **Settings → Servers → Add remote server** |
| Your code | [The API](https://haarness.ai/docs/server/api.md) or [the SDKs](https://haarness.ai/docs/server/sdks.md) |
| An editor | [`haarness acp`](https://haarness.ai/docs/server/acp.md) |

`haarness attach --continue` reopens the last chat, and `--fork` opens a copy of it.

## What keeps running when a client goes away

Chats belong to the server, not to the client. Closing a terminal, quitting Desktop or dropping a
connection does not stop a running turn, its subagents or its terminals. Reconnect and you see the
work where it is. Each chat's [Review, Auto or Yolo](https://haarness.ai/docs/security/permissions.md#review-auto-or-yolo-how-much-does-a-chat-ask)
setting is kept on the server too, so a chat in Auto goes on having its requests reviewed while no
client is open.

To stop work, stop it explicitly:

- **One chat:** `/cancel` in the terminal UI, or
  `POST /v1/threads/{id}/interrupt` from code.
- **The whole server:** `haarness serve --stop`. Any turn still running is interrupted.

## One server per project

Each project folder has at most one server. Its chats, history and settings are its own. Once a
server is running for a folder, Desktop, `haarness` and `haarness run` use it for that folder.

If the folder's server is already running, for example one the terminal UI or Desktop started,
`haarness serve` does not start a second one. It listens at its own address, with its own
password or token, and passes every request to that server. You see:

```text
haarness: Haarness server 4242 already runs /Users/you/code/my-project; this address serves it too, and stopping this command leaves that server running.
Haarness server listening on http://127.0.0.1:4096
```

Stopping that command closes only its address; the chats and their work go on. To stop the
folder's server itself, run `haarness serve --stop`.

## Flags

| Flag | Default | Use it to |
| --- | --- | --- |
| `--port` | `4096`, or a free port | Listen on another port; `0` picks a free one |
| `--host` | `127.0.0.1` | Listen on another address |
| `--password` | none | Require a password |
| `--username` | `haarness` | Change the password's username |
| `--token` | none | Require a bearer token |
| `--anonymous` | off | Listen on a network address with no password or token |
| `--workspace` | `.` | Serve another folder |
| `--yolo` | off | Approve every permission request, for every client |
| `--daemon` | off | Run in the background |
| `--stop` | off | Stop the running server |
| `--log-level` | `info` | Log more (`debug`) or less |

`--password`, `--username` and `--token` can also come from `HAARNESS_SERVER_PASSWORD`,
`HAARNESS_SERVER_USERNAME` and `HAARNESS_SERVER_TOKEN`.

## Troubleshooting

**"… and --yolo cannot change how it approves requests".** The folder's server is already
running, and `--yolo` would change how it approves for everyone. Stop it with
`haarness serve --stop`, then run `haarness serve --yolo` again.

**"Refusing to listen on 0.0.0.0 without a password".** A server on a network address needs a
password or token. See [Connect safely](https://haarness.ai/docs/server/authentication.md#reach-a-server-on-another-machine).

**"This project already has a server with different authentication settings".** `serve --daemon`
found the folder's server running with another password or token setting. Stop it with
`haarness serve --stop`, then start it again with the settings you want.

**"port 4096 … is in use, so this server took a free port".** Another program holds 4096. Connect
to the address on the next line, or free the port and start again.

**Where are the logs?** `serve` prints its log to the terminal. Every server also writes to the
log directory: `haarness logs` shows where it is, and `haarness logs --tail 50` prints the newest
lines.

## Next

- [Connect safely](https://haarness.ai/docs/server/authentication.md) — passwords, tokens and other machines
- [Your first API call](https://haarness.ai/docs/server/api.md) — run a turn and stream the answer