Security and networking

Authentication

Basic authentication

formae supports HTTP Basic Authentication via the auth-basic plugin. Authentication is configured separately for the agent (server-side validation) and the CLI (client-side credentials). Import the plugin's typed configuration 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 = "myUserName"
                // bcrypt salted password hash
                password = "$2y$10$ki1wCrM94EViuTv0dRNEVuP3ujj2/uu2Zh8/FyFvExjZyrsdtr1SS"
            }
        }
    }
}

CLI configuration:

The CLI sends credentials with every request to the agent.

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

Generate bcrypt password hashes:

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

Deprecated configuration. Previous versions configured authentication in a plugins { authentication { ... } } block. This is still supported for backwards compatibility but will be removed in a future release. Migrate to agent.auth and cli.auth as shown above.

---

TLS

Enable TLS for secure agent communication:

agent {
    server {
        hostname = "agent.example.com"
        tlsCert = "/path/to/cert.crt"
        tlsKey = "/path/to/cert.key"
    }
}

See the server settings reference for additional options.

---

Tailscale (experimental)

Connect the agent to your Tailscale network without installing the Tailscale client. This provides secure, centralized access without complex VPC or VPN configuration.

network {
    type = "tailscale"
    tailscale {
        hostname = "formae-agent"
        tls = true
        authKey = "tskey-auth-..."
        advertiseTags {
            "tag:formae"
        }
    }
}

Property	Description
tailscale.hostname	Device name on your tailnet
tailscale.tls	Enable automatic TLS certificate from Tailscale
tailscale.authKey	Tailscale auth key for device registration
tailscale.advertiseTags	Tags for ACL-based access control

Deprecated configuration. Previous versions configured networking in a plugins { network { ... } } block. This is still supported for backwards compatibility but will be removed in a future release. Migrate to the top-level network block as shown above.