Skip to main content

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:
When you run 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/config and ~/.kube/config are 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.
With Transparent Mode, the Formal Endpoint can decide to intercept traffic automatically. It then applies logging, policy enforcement, and optional routing to . The interception criteria for each TCP connection are based on network rules. Once Transparent Mode is on, you do not change existing client applications. One-time setup
  1. Run:
  1. Approve any system prompts so the Formal Endpoint network extension can run.
  2. Start Transparent Mode:
  1. Verify that Transparent Mode is running:
Connect
Replace <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

The Formal Endpoint must be running for CLI commands to work. Enable “Launch at startup” in preferences.
When connecting via formal connect, use tab completion to find resources quickly.
formal ls provides an interactive way to explore and connect to resources without memorizing names.
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