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

# Connect safely

A Haarness server can read and change files in its project and run commands as you. Whoever can
call its API can do the same, including approving their own tool calls. Decide who can reach it
before you start one.

## What the default allows

`haarness serve` listens on `127.0.0.1` and asks for no password. That suits a script or an
editor on your own computer. Other machines cannot reach it.

Web pages are refused unless the Haarness server itself serves them, on the same host and port,
so neither a website you visit nor a development server on another local port can drive the
server through your browser. Programs on your computer can.

## Require a password

```sh
export HAARNESS_SERVER_PASSWORD='choose-a-long-password'
haarness serve
```

Every request now needs HTTP Basic credentials. The username is `haarness` unless you set
`--username`. Requests without them get `401`.

Connect with the same password:

```sh
haarness attach http://127.0.0.1:4096    # reads HAARNESS_SERVER_PASSWORD
curl -u "haarness:$HAARNESS_SERVER_PASSWORD" http://127.0.0.1:4096/v1/info
```

In Desktop, open **Username and password** in the connection form. The SDKs take `password`
(and optionally `username`); see [the SDKs](https://haarness.ai/docs/server/sdks.md).

Prefer the environment variable to `--password`, which can end up in your shell history.

If the folder's server is already running, for example because the terminal UI started it,
`haarness serve` with a password puts that password on the address it opens. The server the
terminal UI and Desktop use keeps its own private credentials.

## Use a token for scripts

```sh
export HAARNESS_SERVER_TOKEN="$(openssl rand -hex 32)"
haarness serve
curl -H "Authorization: Bearer $HAARNESS_SERVER_TOKEN" \
  http://127.0.0.1:4096/v1/info
```

The SDKs and `haarness attach` read `HAARNESS_SERVER_TOKEN` automatically. A password is never
accepted as a bearer token.

To change the password or token, stop the server first with `haarness serve --stop`.

## Reach a server on another machine

The safest setup keeps the server on loopback and forwards a port over SSH. On your own
computer:

```sh
ssh -N -L 4096:127.0.0.1:4096 you@build-box
```

Then connect to `http://127.0.0.1:4096` as if the server were local. Nothing is exposed on the
network, and Desktop accepts the address.

If you must listen on the network, set a password and put the server behind HTTPS or a private
network:

```sh
HAARNESS_SERVER_PASSWORD='…' haarness serve --host 0.0.0.0
```

- The built-in listener speaks plain HTTP. Desktop only connects to a remote server over HTTPS or
  through an SSH tunnel.
- **A network address needs a password or token.** Without one, `haarness serve --host 0.0.0.0`
  refuses to start: `Refusing to listen on 0.0.0.0 without a password`. `--anonymous` starts it
  anyway, and then anyone who can reach the port can run commands as you.
- A web page may call a server on a network address only when the page comes from that same
  address, port included, and names it by IP address or `localhost`.
- A reverse proxy in front of a server on `127.0.0.1` must send `Host: 127.0.0.1` (or
  `localhost`), or the server answers `403`.

## Things that widen access

| Setting | Effect |
| --- | --- |
| `haarness serve --anonymous` | No password or token, even on a network address |
| `haarness serve --yolo` | Every permission prompt is approved, for every client, and remembered until the server stops |
| A chat set to Auto | A reviewer model answers that chat's prompts for every client: it approves routine ones once and leaves or refuses the rest |
| `"autoApprove": true` on a turn | That turn's prompts are approved once each; deny rules still apply |
| Answering a prompt with an "always" choice | Matching calls are allowed for the server, project or repository |

None of these approve the requests that always need a person, such as a Haarness Cloud action that
spends money. See [Permissions](https://haarness.ai/docs/security/permissions.md) for what each prompt protects.

## Where credentials are kept

Desktop stores saved server passwords encrypted by the operating system. Provider keys stay on the
machine that runs the server, in an owner-only file; they are never sent to clients. Servers that
Desktop and the terminal UI start for you use private credentials you never need to copy.

## Next

- [Your first API call](https://haarness.ai/docs/server/api.md)
- [Trust boundaries](https://haarness.ai/docs/security/trust-boundaries.md)