Overview
The Formal Endpoint simplifies connecting to protected resources by automating authentication and connection management. It also includes a powerful CLI. Deploy it on macOS, Windows, Linux, or Kubernetes. Configure startup behavior in~/.formal/config.toml.
The Endpoint runs a background process, started with formal agent, that the CLI talks to. Endpoint guides call it “the agent”. It is unrelated to Formal Agent, the AI assistant in the Control Plane.
Access
Download the Formal Endpoint from the Control Plane. Click Download Endpoint at the bottom of the sidebar, then choose your operating system. Linux packages are under Linux. To roll the Endpoint out to a managed fleet, use MDM Endpoint Rollout.Connecting to Resources
Avoiding Credentials
After you log in, confirm your session with:formal connect for a , the Formal Endpoint injects Formal credentials for you. You do not pass Formal usernames or passwords to the client.
- SSH and Kubernetes: Your
~/.ssh/configand~/.kube/configare updated so tools use the right paths and identity. - Other technologies: A localhost listener is started. Point your client at that address and port without supplying Formal credentials.
Transparent Mode
Transparent Mode is supported on macOS and Linux. On Linux, enable
it in
~/.formal/config.toml. See
Install Formal Endpoint on Linux.- Run:
- Approve any system prompts so the Formal Endpoint network extension can run.
- Start Transparent Mode:
- Verify that Transparent Mode is running:
<resource-name> with the name from formal ls. Traffic to that resource’s hostname then goes through the Connector transparently.
Write network rules to select which flows Transparent Mode intercepts.
Runtime TLS trust
Transparent Mode terminates TLS with certificates from the Formal local CA.formal ca trust adds that CA to the OS trust store, which browsers and Go programs use.
Node.js and most Python HTTP clients ignore the OS trust store and ship their own roots instead.
On macOS, you may want to point these clients at ~/.formal/ca/ca-bundle.pem, a bundle of the OS trust store plus the Formal CA.
Set transparent_proxy.runtime_ca_env = "all" in config.toml.
While the OS trusts the Formal CA, the Endpoint then sets these variables in your login session:
Unless
runtime_ca_env is none, the Endpoint also sets NODE_EXTRA_CA_CERTS, SSL_CERT_FILE, and REQUESTS_CA_BUNDLE in Claude Code’s ~/.claude/settings.json.
Variables that are already set keep their values.
Apps and terminals opened afterward inherit the variables. Restart apps that were already open.
Best Practices
Keep App Running
Keep App Running
The Formal Endpoint must be running for CLI commands to work. Enable “Launch at
startup” in preferences.
Use Descriptive Resource Names
Use Descriptive Resource Names
When connecting via
formal connect, use tab completion to find resources
quickly.Leverage the TUI
Leverage the TUI
formal ls provides an interactive way to explore and connect to resources
without memorizing names.Disconnect When Done
Disconnect When Done
Always disconnect from resources when finished to free up local ports.
Next Steps
Deploy on macOS
Roll out the Endpoint with your MDM
Log In with OIDC
Authenticate as a machine identity
CLI Reference
Connect to resources from the terminal
Configuration
Configure
~/.formal/config.toml