Formal Endpoint

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 Endpoint so it reloads ~/.formal/config.toml.

formal auth login
formal auth whoami
formal ls

formal auth whoami should show the matching machine identity.

Log In with an API Key

Use an API key when the Formal Endpoint should skip the browser login flow. This works for human users and machine users.

Create an API key

Go to API Keys and click Create API Key.To authenticate as a machine user, assign the key to that machine user.

Start the Formal Endpoint

FORMAL_API_KEY=<api-key> formal agent

For a server without a GUI or keyring, add --headless:

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

Verify

formal auth whoami

The output should show the human or machine user that owns the key.

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 Endpoint network extension can run.
Start the transparent proxy:

formal transparent-proxy enable

Verify that the transparent proxy is running:

formal transparent-proxy status

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`
`transparentProxyInterceptLocalhost`	bool	`transparent_proxy.intercept_localhost`

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

Specify Resource Hostname

If a resource has multiple Resource Hostnames (for example, separate reader and writer endpoints), target one by appending @<hostname-name> to the resource name:

# Connect to the "postgres-reader" hostname on the production-postgres resource
formal connect production-postgres@postgres-reader

Resource hostname targeting is currently supported for PostgreSQL and MySQL resources.

Connect with your database client as usual, using the port from the formal connect output:

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

# MySQL
mysql -h localhost -P 4306 -D mysql

Use the same RESOURCE_NAME@HOSTNAME_NAME target to disconnect:

formal disconnect production-postgres@postgres-reader

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

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 Endpoint 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). To skip formal auth login in headless mode, start the agent with an API key.

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.

Getting Started

Configuring Formal

Leveraging Formal

Integrations

Configuration

Client Apps

Example Use Cases

Overview

Access

Setup

Log In with AWS SigV4

Log In with an API Key

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

Specify Resource Hostname

SSH

Kubernetes

Disconnect

Decrypt Data

S3 Operations

Device Trust

Headless Mode

MDM Deployment

Troubleshooting

Best Practices

​Overview

​Access

​Setup

​Log In with AWS SigV4

​Log In with an API Key

​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

​Specify Resource Hostname

​SSH

​Kubernetes

​Disconnect

​Decrypt Data

​S3 Operations

​Device Trust

​Headless Mode

​MDM Deployment

​Troubleshooting

​Best Practices

Overview

Access

Setup

Log In with AWS SigV4

Log In with an API Key

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

Specify Resource Hostname

SSH

Kubernetes

Disconnect

Decrypt Data

S3 Operations

Device Trust

Headless Mode

MDM Deployment

Troubleshooting

Best Practices