Formal Endpoint - Formal Documentation

Overview

The Formal Endpoint simplifies connecting to protected resources by automating authentication and connection management. It also includes a powerful CLI.

Access

Contact Formal support or your workspace administrator for approved Formal Endpoint distribution and deployment guidance.

Setup

Launch the App

Start Formal - you’ll see the logo in your system tray

Install CLI (macOS)

Click the tray icon → Preferences → Install in PATH.Or manually:

sudo ln -s /Applications/Formal.app/Contents/MacOS/formal /usr/local/bin/formal

formal auth login

Verify

formal ls

You should see all available resources.

Log In with AWS SigV4

Use AWS SigV4 when the Formal Endpoint should authenticate as a Formal machine identity.

AWS SigV4 desktop login requires a Formal machine identity. Its name must match your AWS principal name.

Set up AWS SigV4 auth

Complete the AWS SigV4 authentication prerequisites. You can skip the API usage examples.This includes creating an active AWS cloud integration in Formal.

Verify your local AWS identity

Confirm the Formal Endpoint host can call AWS STS:

aws sts get-caller-identity

The returned AWS principal must match the Formal machine identity.

Configure the Formal Endpoint

Add this setting to ~/.formal/config.toml:

auth_mode = "aws_sigv4"

If auth_mode already exists, replace its value instead of adding another line.

Restart and log in

Restart the Formal Formal Endpoint so it reloads ~/.formal/config.toml.

formal auth login
formal auth whoami
formal ls

formal auth whoami should show the matching machine identity.

Connecting to Resources

Avoiding Credentials

After you log in, confirm your session with:

formal auth whoami

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 Proxy

Transparent proxy is supported on macOS only.

The Formal Endpoint can route traffic for a resource hostname through the Formal . You use the resource’s real hostname. You do not apply Formal credentials on the client. One-time setup

Run:

formal transparent-proxy install

Approve any system prompts so the Formal Formal Endpoint network extension can run.
Start the transparent proxy:

formal transparent-proxy enable

Connect

formal connect <resource-name>

Replace <resource-name> with the name from formal ls. Traffic to that resource’s hostname then goes through the Connector transparently.

CLI Reference

Optional Update Checks

Formal Endpoint update checks are disabled by default. To enable update polling and the tray update icon, add this to ~/.formal/config.toml:

check_for_updates = true

Hide the Tray Icon

To run the Formal Endpoint without a system tray icon, add this to ~/.formal/config.toml:

hide_systray_icon = true

The agent keeps running in the background, but the tray icon is hidden so users cannot interact with it.

Managed Preferences (MDM overrides)

On macOS, MDM administrators can override any ~/.formal/config.toml setting through the com.formal.desktop managed-preferences domain. Deploy the values as Forced (locked) keys in a com.apple.ManagedClient.preferences payload. Forced managed preferences take precedence over config.toml and apply even when the file is absent. Available keys:

Managed preference key	Type	config.toml setting
`checkForUpdates`	bool	`check_for_updates`
`hideSystrayIcon`	bool	`hide_systray_icon`
`transparentProxyEnable`	bool	`transparent_proxy.enable`
`transparentProxyEnforce`	bool	`transparent_proxy.enforce`
`transparentProxyFail`	string	`transparent_proxy.fail` (`open` or `closed`)
`transparentProxyAllowQuic`	bool	`transparent_proxy.allow_quic`

See the profile templates in fixtures/mdm_setup/ for a full example payload.

Authentication

# Log in
formal auth login

# Get your credentials (for direct connections)
formal auth credentials

List Resources

formal ls

Interactive TUI with:

↑/k - Move up
↓/j - Move down
enter - Connect to resource
/ - Filter resources
q - Quit
? - Show help

Connect to Resources

Databases (PostgreSQL, MySQL, MongoDB)

# Connect to a database
formal connect production-postgres

# Output:
# Connected to production-postgres on localhost:6432

Then connect with your database client:

# PostgreSQL
psql -h localhost -p 6432 -d postgres

# MySQL
mysql -h localhost -P 6432 -d mysql

# MongoDB
mongosh "mongodb://localhost:27017/mydb"

Formal automatically injects your credentials - no username/password needed! Note that the database name is required for the connection to be successful. You can also use the --launch argument to launch the appropriate CLI program after connecting (for example psql or ssh), e.g.

# uses the database name from the config file in ~/.formal/config.toml
formal connect --launch production-postgres

Specify Native User

If you need to specify a different native user than the default one assigned to your user, you can specify it using the convention: formal@[the_name_of_the_native_user].

# PostgreSQL with specific native user
psql -h localhost -p 6432 -U formal@readonly

SSH

# List resources
formal ls
# Select an SSH resource and press enter

This updates your ~/.ssh/config automatically.

Kubernetes

# Configure kubectl
formal ls
# Select a Kubernetes resource and press enter

This updates your ~/.kube/config to route through the Connector.

Disconnect

# Disconnect from a resource
formal disconnect production-postgres

Policy Evaluation

Test policies locally:

formal policy evaluate \
  --inputs '{"user_id":"abc123"}' \
  -r session

Decrypt Data

Decrypt Formal-encrypted data:

formal decrypt --ciphertext "formalencrypt:second:third:fourth:fifth"

S3 Operations

The Formal s3 command automatically routes traffic to the right Connector so your users don’t have to worry about formatting the right parameters for S3. Interact with S3 through Formal:

formal s3 ls s3://my-bucket

See AWS CLI S3 commands for more operations.

Device Trust

The Formal Endpoint reports device information for policy enforcement:

Hardware model and serial number
OS version and security settings
System Integrity Protection status
Secure boot status

See MDM Integration for device-based policies.

Headless Mode

The Formal Desktop app supports being launched in headless mode. This can be useful in server environments without a GUI or keyring support. To start the agent in headless mode, you can use the following command:

formal agent --headless

Now in a separate terminal, you can run the Formal CLI as normal to connect to resources and get credentials:

formal auth login
formal auth credentials
formal ls
formal connect [resource-name]

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

Using an API Key

The Formal Desktop app supports using an API key to authenticate to the Control Plane. First, you will need to create an API key on the Formal Console. Create one under API Keys in the console. To start the agent with an API key, you can use the following command:

FORMAL_API_KEY=<api-key> formal agent

You can also run the agent in headless mode with an API key:

FORMAL_API_KEY=<api-key> formal agent --headless

MDM Deployment

Deploy the Formal Endpoint organization-wide via your MDM with an approved package from Formal support:

Request the approved deployment package from Formal support.
Add it as a custom app in your MDM (Jamf, Intune, etc.).
Push it to all user devices.

Need help deploying via MDM? Contact Formal support for assistance.

Troubleshooting

App not running

Error: WARNING: CLI cannot connect to the Formal app. Please make sure the Formal app is running.Solution:

Check that Formal is visible in system tray
Restart the Formal app
On Linux: systemctl start --user formal

Command not found

Error: bash: formal: command not foundSolution:

Reinstall CLI: Click tray icon → Preferences → Install in PATH
Or create symlink manually (see Setup section)
Or add alias to .bashrc/.zshrc

Connection fails

Solution:

Check resource exists: formal ls
Ensure Connector is running
Check network connectivity

Best Practices

Keep App Running

The Formal Endpoint must be running for CLI commands to work. Enable “Launch at startup” in preferences.

Use Descriptive Resource Names

When connecting via formal connect, use tab completion to find resources quickly.

Leverage the TUI

formal ls provides an interactive way to explore and connect to resources without memorizing names.

Disconnect When Done

Always disconnect from resources when finished to free up local ports.

​Overview

​Access

​Setup

​Log In with AWS SigV4

​Connecting to Resources

​Avoiding Credentials

​Transparent Proxy

​CLI Reference

​Optional Update Checks

​Hide the Tray Icon

​Managed Preferences (MDM overrides)

​Authentication

​List Resources

​Connect to Resources

​Databases (PostgreSQL, MySQL, MongoDB)

​Specify Native User

​SSH

​Kubernetes

​Disconnect

​Policy Evaluation

​Decrypt Data

​S3 Operations

​Device Trust

​Headless Mode

​Using an API Key

​MDM Deployment

​Troubleshooting

​Best Practices

Overview

Access

Setup

Log In with AWS SigV4

Connecting to Resources

Avoiding Credentials

Transparent Proxy

CLI Reference

Optional Update Checks

Hide the Tray Icon

Managed Preferences (MDM overrides)

Authentication

List Resources

Connect to Resources

Databases (PostgreSQL, MySQL, MongoDB)

Specify Native User

SSH

Kubernetes

Disconnect

Policy Evaluation

Decrypt Data

S3 Operations

Device Trust

Headless Mode

Using an API Key

MDM Deployment

Troubleshooting

Best Practices