Skip to content
aarness.
DocsServer & SDKs
On this page

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, an editor 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:

cd ~/code/my-project
haarness serve

You will see:

Haarness server listening on http://127.0.0.1:4096

Check it from another terminal:

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 before you change that.

Run it in the background

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 or the SDKs
An editor haarness acp

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

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.

"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