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 api.joinformal.com
The package supports amd64 and arm64.

​
Install

1

Download the package

In the Control Plane, click Download Formal Endpoint at the bottom of the sidebar. Open Linux and pick the headless package for your architecture:
  • Ubuntu/Debian (x86, headless) for amd64
  • Ubuntu/Debian (ARM, headless) for arm64
Print the host architecture with dpkg --print-architecture. Copy the .deb file to the host, for example with scp.
2

Install the package

Verify:
3

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:
4

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.
5

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.

​
Headless Mode

The Formal Endpoint supports being launched in headless mode. This can be useful in server environments without a GUI or keyring support. In this guide, “the agent” means the Endpoint’s background process that formal agent starts. It is not the Control Plane’s Formal Agent assistant. To start the agent in headless mode, you can use the following command:
Now in a separate terminal, you can run the Formal CLI as normal to connect to resources and get credentials:
In headless mode, Formal credentials are only stored in the agent’s memory. This means that you’ll need to reauthenticate when restarting the agent (e.g., when the machine itself reboots). To skip formal auth login, configure OIDC or start the agent with an API key. On Linux, the Debian package installs a formal.service user unit.

​
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

Grok Bot

Install the Endpoint on Grok Bot computers