Skip to main content

​
Overview

Install the headless Formal Endpoint package on Debian or Ubuntu. The package adds the formal CLI and a systemd user service that runs formal agent --headless. Enable Transparent Mode to intercept host traffic, including traffic from coding agents. For Kubernetes, use the Kubernetes egress sidecar instead of this package.

​
Prerequisites

  • A Debian or Ubuntu host with sudo and systemd
  • A Formal API key from API Keys
  • Outbound HTTPS to static-assets.formalcloud.net and api.joinformal.com
The package supports amd64 and arm64.

​
Install

1

Download and install the package

The latest package URL includes the host architecture:
Pin a versioned package URL when your rollout requires a fixed version.Verify:
2

Grant access to the local CA directory

The Endpoint writes its local CA to /var/lib/formal/ca. Your user must be able to write that directory:
3

Configure the API key and Transparent Mode

Create ~/.formal and store the API key in formal.env. The user service loads that file on start.
Replace <YOUR_API_KEY> with a key from API Keys. See Configuration for other config.toml keys. To skip long-lived keys, use OIDC.
4

Enable lingering and start the service

Lingering lets systemd start the user service without an interactive login. This is required on servers and VMs.
Verify:

​
Verify

formal auth whoami should show the user that owns the API key. The Transparent Mode status should be enabled. Write network rules to select which flows Transparent Mode intercepts. On Linux, match a hostname or is_llm_hostname. Linux has no process signing identity.
Read service logs with journalctl --user -u formal.service. Set XDG_RUNTIME_DIR first when your shell has no session bus.

​
Troubleshooting

Confirm lingering is enabled with loginctl show-user "$(id -un)". Set XDG_RUNTIME_DIR="/run/user/$(id -u)" and read failures with journalctl --user -u formal.service. Then run systemctl --user enable --now formal.service.
Error: WARNING: CLI cannot connect to the Formal app.The CLI talks to the user service over a local socket. Confirm formal.service is active, then retry formal auth whoami.
The Endpoint must write /var/lib/formal/ca. Re-run:
Then restart the service.
Confirm ~/.formal/config.toml sets transparent_proxy.enable = true. Confirm formal transparent-proxy status is enabled. Confirm a network rule matches the destination. Without a matching rule, the Endpoint forwards the connection without inspecting it.

​
Next Steps

Formal Endpoint

Review authentication and connection options

Configuration

Set config.toml keys for the Endpoint

Network Rules

Select which traffic Transparent Mode intercepts

Cloud Agents

Run the Endpoint inside Cursor and Devin agents