Security and networking

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.

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 section of the configuration reference.

HTTP Basic Authentication

formae supports HTTP Basic Authentication via the auth-basic plugin, the default HTTP Basic Authentication option. Each auth plugin ships its own typed configuration that you import through the plugins:/ scheme:

import "plugins:/AuthBasic.pkl" as AuthBasic

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

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.

cli {
    auth = new AuthBasic.CliConfig {
        username = "alice"
        password = "mySecretPass"
    }
}

Generate a bcrypt password hash with htpasswd:

htpasswd -bnBC 10 "" yourPassword | tr -d ':'

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.

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, which default to null.

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 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 block, whose type field names the network plugin.

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

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.

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 and CLI for the full list of options.

Get started

Guides

Concepts

Reference

Security and networking

Authentication

HTTP Basic Authentication

TLS

Tailscale (experimental)

Ports

See also

​Authentication

​HTTP Basic Authentication

​TLS

​Tailscale (experimental)

​Ports

​See also

Authentication

HTTP Basic Authentication

TLS

Tailscale (experimental)

Ports

See also