﻿RunWisp has two ways in:

- The CLI and TUI on the same machine use the control socket. No password.
- The Web UI and anything else over HTTP need the password. Scripts can use an
  [API token](#api-tokens) instead.

## Local clients (CLI, TUI)

`runwisp`, `runwisp tui`, `runwisp status`, `runwisp run`, and the other
commands talk to the daemon over the [control socket](/reference/cli/#control-socket).
Only the user who started the daemon can open it, so there's nothing to log in
to. Anyone who can read the data directory controls the daemon.

With `--url` (or `RUNWISP_URL`), `runwisp run` and `runwisp tui` connect over
HTTP instead and log in like any network client.

If the CLI prints `daemon is not reachable at <path>` while a daemon is up, the
two are using different data directories. Check `--data` and which user you're
running as.

## Network clients (Web UI, remote REST)

The Web UI asks for the password once, then keeps you logged in with a session
cookie for 24 hours. The password itself never crosses the network: login is a
challenge and response. To log in from a script, use `runwisp run --url` or the
script in [Remote triggers](/recipes/remote-trigger/).

The session cookie and run output are only as private as the connection. When
you bind beyond loopback, turn on [TLS](/configuration/daemon/#tls-tls_cert-tls_key)
or put the daemon behind a [reverse proxy](#reverse-proxies) that does.

The TUI's **Open in browser** logs the browser in with a single-use ticket that
expires after 60 seconds. When `runwisp tui --url` points at a plain `http://`
address that isn't loopback, the TUI warns you first, because the ticket would
cross the network unencrypted.

## The password

```bash
RUNWISP_PASSWORD='long-random-string' runwisp daemon
```

- **Set `RUNWISP_PASSWORD`.** The daemon reads it from the environment and keeps
  it in memory. Browser sessions survive a restart as long as the value doesn't
  change. Keep the value in whatever secret store you already use.
- **Leave it unset.** The daemon makes up a new random password on every boot,
  so each restart logs everyone out. Fine for a daemon you start by hand;
  annoying for one that runs for months.

[`runwisp service install`](/operations/autostart/#a-stable-web-ui-password)
generates a stable password for you, so an installed daemon doesn't have this
problem.

To rotate the password, change `RUNWISP_PASSWORD` (or unset it) and restart.
Every network session ends.

RunWisp never writes the password or the session signing key to disk.

### Getting the generated password

```bash
runwisp password | wl-copy   # Linux, Wayland
runwisp password | pbcopy    # macOS
```

In the TUI, open **Home**, focus the `Password` row, and press <kbd>Enter</kbd>
to copy it.

`runwisp password` works only over the control socket, and only for a generated
password. It exits `1` when `RUNWISP_PASSWORD` is set (RunWisp never hands out a
password you chose) and `5` when authentication is off. Piping it into a
clipboard tool keeps it out of your scrollback.

The system service's socket belongs to root, so ask it with
`sudo runwisp password`.

## Read-only access

**since**: `1.7`

```bash
RUNWISP_PASSWORD='long-random-string' \
RUNWISP_VIEWER_PASSWORD='another-string' runwisp daemon
```

A second password lets someone look at the dashboard without being able to
change anything. It's off unless you set it: with no `RUNWISP_VIEWER_PASSWORD`
there is no second secret and nobody can sign in read-only.

Someone who signs in with it can see tasks, runs, logs and notifications. The
daemon rejects everything that changes state with a `403`: triggering, starting,
stopping or restarting a task, pausing, deleting runs, reloading the config and
marking notifications read. The Web UI hides those controls and shows a
**Read-only** badge in the top bar. A remote `runwisp tui --url` hides them too
and marks the sidebar **read-only**. A remote `runwisp run --url` signed in this
way fails with a message saying so.

- The two passwords must differ. The daemon refuses to start if they match.
- It can't be combined with `RUNWISP_AUTH=off`.
- Changing it ends read-only sessions only; full sessions carry on.
- It can't be used to get the full password: a read-only session can't mint a
  launch ticket (see [Network clients](#network-clients-web-ui-remote-rest)).
- The control socket is unaffected. Local clients always have full access.

To get a read-only password without setting one in the environment, ask the
running daemon for it:

```bash
runwisp password --viewer
```

The first call makes up a random password and keeps it in memory until the
daemon restarts; later calls print the same one. Like `runwisp password`, it
exits `1` when `RUNWISP_VIEWER_PASSWORD` is set.

## API tokens

**since**: `1.9`

A script or monitoring job can call the REST API with a static token instead of
logging in. Make one and put it in the daemon's environment:

```bash
openssl rand -hex 32
export RUNWISP_API_TOKEN='the-value-it-printed'
```

Name it in `runwisp.toml` with [substitution](/configuration/substitution/), so
the secret stays out of the file, then run `runwisp reload`:

```toml title="runwisp.toml"
[daemon]
api_tokens = ["${RUNWISP_API_TOKEN}"]
```

Send it as a bearer header:

```bash
curl -fsS -H "Authorization: Bearer $RUNWISP_API_TOKEN" \
  https://runwisp.example.com:9477/api/tasks
```

- A token from [`api_tokens`](/configuration/daemon/#api_tokens) can do
  everything a signed-in operator can, including triggering and stopping tasks.
- A token from [`viewer_api_tokens`](/configuration/daemon/#viewer_api_tokens)
  is read-only: anything that changes state gets `403`, like a
  [read-only session](#read-only-access).
- A token never expires. To rotate one, change the value and reload. The old
  value stops working at once; sessions and other tokens carry on.
- Tokens work in place of the session token on every `/api/` route. They don't
  replace [hooks](#hooks), which control a single task. They are for scripts,
  not for the Web UI, and `runwisp run --url` still takes the password.
- Use TLS or a [reverse proxy](#reverse-proxies) off loopback. A token in plain
  HTTP can be read on the way.

## Running without a password

```bash
RUNWISP_AUTH=off runwisp daemon
```

The API and Web UI answer every request without a password. **Anyone who can
reach the port can read every log and run any task** as the user that started
the daemon. Use it for local development or on an isolated network, never on a
port the internet can reach. If you need remote access without a RunWisp login,
put a proxy that does its own authentication in front.

- `RUNWISP_AUTH` accepts `off` or `on` (any case). Any other value stops the
  daemon at startup.
- It can't be combined with `RUNWISP_PASSWORD`; the daemon refuses to start with
  both.
- The daemon prints a warning at startup, the Web UI shows an **Auth disabled**
  badge, and the TUI shows the password as disabled.
- The control socket works the same as before.

The official Docker image won't start until you choose `RUNWISP_PASSWORD` or
`RUNWISP_AUTH=off`. For a passwordless local container, publish the port on
loopback only:

```bash
docker run --rm -e RUNWISP_AUTH=off -p 127.0.0.1:9477:9477 \
  -v ./runwisp:/etc/runwisp runwisp/runwisp:latest
```

## Hooks

A CI job or webhook can control one task or service without the password. Give
it a [`hook_tokens`](/configuration/tasks/#hook_tokens) entry, then send the
token as a bearer header:

```bash
curl -fsS -X POST -H "Authorization: Bearer $CI_DEPLOY_TOKEN" \
  "https://runwisp.example.com:9477/api/hooks/tasks/deploy/run?wait=true"
```

Each hook is a session route under `/api/hooks/`, with the same query, body, and
response:

| Hook                                   | Same as                          |
| -------------------------------------- | -------------------------------- |
| `POST /api/hooks/tasks/{name}/run`     | `POST /api/tasks/{name}/run`     |
| `POST /api/hooks/tasks/{name}/start`   | `POST /api/tasks/{name}/start`   |
| `POST /api/hooks/tasks/{name}/stop`    | `POST /api/tasks/{name}/stop`    |
| `POST /api/hooks/tasks/{name}/restart` | `POST /api/tasks/{name}/restart` |

Add `?wait=true` to hold the request until the work is done:

- `run`, `start`, `restart` on a task: returns the finished run with its
  `exitCode` and `endReason`. `start` on a task that is already running waits
  for that run.
- `stop`: returns once every run has ended, or `409` if some are still ending
  when `waitTimeout` (seconds, default `120`) runs out.
- `start`, `restart` on a service: `400`, since a service instance doesn't end
  on its own.

A hook token can't read run logs. Since 1.8, `run` takes `tail=N` (up to
`1000`) and adds the last `N` lines of the run's log to the response as a `log`
array of `{n, stream, text}`, so a CI job can show why a run failed:

```bash
curl -fsS -X POST -H "Authorization: Bearer $CI_DEPLOY_TOKEN" \
  "https://runwisp.example.com:9477/api/hooks/tasks/deploy/run?wait=true&tail=50" \
  | jq -r '.log[].text'
```

Runs started this way show as triggered by `hook`.

If a webhook sender can only set a URL, pass the token as a query parameter
instead. The header wins when both are sent.

```text
https://runwisp.example.com:9477/api/hooks/tasks/deploy/run?token=<token>
```

:::caution
A token in the URL is insecure. Proxies, CI logs, browser history, and the
webhook sender's own dashboard can all record it. Use the header whenever you
can, and give URL callers their own token so you can rotate it on its own.
:::

A missing or wrong token gets `401`, and so does an unknown task, so hooks don't
reveal which tasks exist. A valid token whose `allow` list leaves out the action
gets `403`. Tokens are checked even with `RUNWISP_AUTH=off`, and
[`manual_trigger`](/configuration/tasks/#manual_trigger) doesn't apply. A rotated
token takes effect on [`runwisp reload`](/operations/reload/).

## Rate limiting

Only wrong passwords count, per client IP. The first 5 cost nothing. After
that, each one doubles the wait before the next try: 2 seconds, then 4, 8, and
so on up to 90 seconds. Trying sooner gets `429 Too Many Requests` with a
`Retry-After` header, even with the right password. A successful login clears
the count, and so do 15 minutes without a wrong password. A restart also
clears it.

Launch tickets and the control socket aren't limited. Challenges are capped at
60 per minute per IP.

[Hooks](#hooks) are limited by failures only: after 20 rejected tokens from one
client IP within a minute, that IP gets `429` (even with a valid token) until
the window moves on. Successful calls never count.

[API tokens](#api-tokens) work the same way, with their own count: after 20
wrong API tokens from one client IP within a minute, that IP gets `429` for
every API token, the right one included, until the window moves on. RunWisp
logs one warning per lockout, without the token. Session cookies, session
tokens and password logins from that IP keep working, and an expired session
never counts as a wrong token.

Live log streams are capped at 128 open at once, and 16 per client IP. Past the
cap, new streams get `503 Service Unavailable`. Close some log views and try
again.

## Reverse proxies

Use a reverse proxy (nginx, Caddy, Traefik, Cloudflare Tunnel) when you need a
publicly trusted certificate. Let the proxy handle TLS, keep RunWisp on plain
HTTP behind it, and tell RunWisp which addresses the proxy connects from:

```toml title="runwisp.toml"
[daemon]
trusted_proxies = ["127.0.0.1/32", "10.0.0.0/8"]
```

From those addresses only, RunWisp trusts:

- `X-Forwarded-For`, so logs and the login throttle see the real client IP.
- `X-Forwarded-Proto: https`, so the session cookie is marked `Secure`.

Without it, every client looks like the proxy, so one client's wrong passwords
slow down logins for everyone, and one script's wrong tokens lock every client
out of hooks and API tokens for a minute. When proxy headers arrive from an address that
isn't in the list, RunWisp logs a warning and adds one to the notification bell.

Keep the list tight: an address in it can claim to be any client IP, and so use
up another client's login limit. The
`RUNWISP_TRUSTED_PROXIES` environment variable (comma-separated) overrides the
key. See [`trusted_proxies`](/configuration/daemon/#trusted_proxies).

Serve RunWisp at the root of its own host name, such as
`runwisp.example.com`. A path prefix like `example.com/runwisp/` doesn't work,
because the Web UI loads its files from `/`.

A minimal nginx site:

```nginx title="/etc/nginx/sites-available/runwisp"
server {
    listen 443 ssl;
    server_name runwisp.example.com;
    # ssl_certificate and ssl_certificate_key go here

    location / {
        proxy_pass http://127.0.0.1:9477;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}
```

The same with Caddy, which gets the certificate for you:

```text title="Caddyfile"
runwisp.example.com {
    reverse_proxy 127.0.0.1:9477
}
```

Live logs and Web UI updates use long-lived streams. RunWisp tells nginx not to
buffer them and sends a keepalive every 30 seconds, so the default
`proxy_read_timeout` of 60 seconds is enough. If your proxy times out idle
connections sooner, raise that limit.

For a LAN or a tailnet, you don't need a proxy:
[`tls = "auto"`](/configuration/daemon/#tls-tls_cert-tls_key) serves HTTPS with
a self-signed certificate.

## Public endpoints

These answer without a password:

- `GET /health`: always `200 OK`. Use it as a liveness probe.
- `GET /metrics`: when [metrics](/operations/metrics/) are on and share the main
  listener.
- `/api/auth/*`: login status, challenge, login, and launch-ticket redemption.
- `POST /api/hooks/*`: needs one of the unit's [hook tokens](#hooks) instead,
  in the header or the URL.
- `GET /api/daemon/identity`: tells a starting `runwisp` which daemon holds the
  port. Loopback and socket callers only; `403` for everyone else.
- The Web UI's static files.

Everything else under `/api/` needs a session or the control socket.

The login response is PBKDF2-HMAC-SHA256 (600,000 rounds) of the password,
salted with a single-use challenge, so a captured login is slow to brute-force.
It doesn't protect the session token; TLS does.
