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

# Security and networking

> Reference for securing and reaching the formae agent: HTTP Basic Authentication, TLS, Tailscale networking, and the default API port.

The formae agent runs inside your infrastructure and exposes a REST API that the CLI talks to. This page is the reference for how that endpoint is secured and reached: authentication, TLS, Tailscale networking, and ports. For the full configuration file layout, see [Configuration](/documentation/reference/configuration).

## Authentication

Authentication is configured separately for the agent and the CLI. The `agent.auth` block controls server-side validation; the `cli.auth` block provides the credentials the CLI sends with every request. Both fields are optional. If `agent.auth` is unset, the agent serves unauthenticated requests. When the agent rejects a request, the CLI receives a `401 Unauthorized` response.

This mirrors the [Authentication](/documentation/reference/configuration#authentication) section of the configuration reference.

### HTTP Basic Authentication

formae supports HTTP Basic Authentication via the [auth-basic](https://github.com/platform-engineering-labs/formae-plugin-auth-basic) plugin, the default HTTP Basic Authentication option. Each auth plugin ships its own typed configuration that you import through the `plugins:/` scheme:

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
import "plugins:/AuthBasic.pkl" as AuthBasic
```

**Agent configuration.** The agent validates incoming requests against a list of authorized users with bcrypt-hashed passwords.

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
agent {
    auth = new AuthBasic.AgentConfig {
        authorizedUsers {
            new AuthBasic.AuthorizedUser {
                username = "alice"
                // bcrypt salted password hash
                password = "$2y$10$ki1wCrM94EViuTv0dRNEVuP3ujj2/uu2Zh8/FyFvExjZyrsdtr1SS"
            }
        }
    }
}
```

**CLI configuration.** The CLI sends these credentials with every request to the agent.

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
cli {
    auth = new AuthBasic.CliConfig {
        username = "alice"
        password = "mySecretPass"
    }
}
```

Generate a bcrypt password hash with `htpasswd`:

```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
htpasswd -bnBC 10 "" yourPassword | tr -d ':'
```

<Note>
  Earlier releases configured authentication under a `plugins { authentication { ... } }` block. That block is still accepted for backwards compatibility but emits deprecation warnings at startup. Migrate to `agent.auth` and `cli.auth` as shown above.
</Note>

## TLS

Enable TLS on the agent's HTTP server by pointing it at a certificate and private key. These are the `tlsCert` and `tlsKey` fields on the [server settings](/documentation/reference/configuration#server-settings), which default to `null`.

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
agent {
    server {
        hostname = "agent.example.com"
        tlsCert = "/path/to/cert.crt"
        tlsKey = "/path/to/cert.key"
    }
}
```

When TLS is enabled, point the CLI at the `https://` URL for the same host through the [`cli.api`](/documentation/reference/configuration#cli) settings.

## Tailscale (experimental)

Connect the agent to your Tailscale network without installing the Tailscale client on the host. This gives you secure, centralized access without additional VPC or VPN configuration. Tailscale is selected through the top-level [`network`](/documentation/reference/configuration#network) block, whose `type` field names the network plugin.

```kotlin theme={"languages":{"custom":["/languages/pkl.json"]}}
network {
    type = "tailscale"
    tailscale {
        hostname = "formae-agent"
        tls = true
        authKey = "tskey-auth-..."
        advertiseTags {
            "tag:formae"
        }
    }
}
```

| Property        | Type           | Default | Description                                           |
| --------------- | -------------- | ------- | ----------------------------------------------------- |
| `authKey`       | String         | none    | Tailscale auth key for device registration (required) |
| `hostname`      | String?        | `null`  | Device name on your tailnet                           |
| `tls`           | Boolean        | `false` | Request an automatic TLS certificate from Tailscale   |
| `advertiseTags` | List\<String>? | `null`  | Tags for ACL-based access control                     |

<Note>
  Earlier releases configured networking under a `plugins { network { ... } }` block. That block is still accepted for backwards compatibility but emits deprecation warnings at startup. Migrate to the top-level `network` block as shown above.
</Note>

## Ports

The agent listens on a single API port. The CLI reaches the agent by combining `cli.api.url` with `cli.api.port`.

| Setting             | Default              | Description                              |
| ------------------- | -------------------- | ---------------------------------------- |
| `agent.server.port` | `49684`              | Port the agent API listens on            |
| `cli.api.url`       | `"http://localhost"` | Base URL the CLI uses to reach the agent |
| `cli.api.port`      | `49684`              | Port the CLI uses to reach the agent     |

Keep the agent's `server.port` and the CLI's `api.port` in agreement. When the agent runs on another host, set `cli.api.url` (and `cli.api.port` if you changed it) to point at that host. See [Server settings](/documentation/reference/configuration#server-settings) and [CLI](/documentation/reference/configuration#cli) for the full list of options.

## See also

* [Configuration](/documentation/reference/configuration): the complete configuration file reference, including the `agent.auth`, `cli.auth`, `server`, `network`, and `cli` sections referenced above.
* [Architecture](/documentation/concepts/architecture): how the CLI and agent communicate.
* [Install the agent](/documentation/guides/install-agent): deploying the agent into your infrastructure.