Skip to main content

Signadot CLI

The Signadot CLI provides a command-line interface to the Signadot API and support for running Local Workloads within Sandboxes.

Installing the CLI

To install the CLI, download and extract the latest release archive for your platform, or use Homebrew (on either macOS or Linux):

brew tap signadot/tap
brew install signadot-cli

The CLI can also be installed and run on-demand via its docker image

Upgrading the CLI

If you used brew, you can run the following commands to upgrade the CLI installation.

brew update
brew upgrade signadot-cli


The CLI reads configuration from a file stored at $HOME/.signadot/config.yaml. This file contains information for using the CLI as an interface to Signadot API and also for running Local Sandboxes. Some parameters in this file can also be set via environment variables.

API Credentials

To talk to the Signadot API, the CLI needs your Signadot org name as well as a Signadot API key, which you can generate in the dashboard.

These values can be provided in a file stored at $HOME/.signadot/config.yaml:

org: ...
api_key: ...

Or you can provide them as environment variables:

export SIGNADOT_ORG=...

Local Configuration


Local configuration is intended for versions v0.5.0+ of the Signadot CLI.

To configure the CLI for running Local Workloads as part of sandboxes, you will need to add a section local to your config file. Here is a minimal local section to get up and running:

- cluster: staging # signadot cluster name
kubeContext: staging-context # kubecontext name for the cluster

It is comprised of a list of connections, each of which defines parameters for communicating directly with a single Kubernetes cluster.

  • The cluster field specifies the name of the Signadot cluster. You can find this value via the dashboard. This field will also correspond to the cluster field in the sandbox specification.
  • The kubeContext field specifies the name of the corresponding context in your kubeConfig file.

Advanced Local Configuration


type defines the connection method. It can be one of PortForward or ProxyAddress. If unspecified, it defaults to PortForward. PortForward uses Kubernetes Port Forwarding to access the cluster. Under the hood, it accesses a SOCKS5 proxy running as part of the Signadot Operator.

type: ProxyAddress is intended for a case where a cluster administrator makes the SOCKS5 proxy available to the local machine, for example by exposing a LoadBalancer pointing to the SOCKS5 proxy within a VPN. When doing so, the SOCKS5 proxy is given a TCP address. With type: ProxyAddress, one does not need to specify kubeContext.

For example, assuming a the SOCKS5 proxy is available at

- cluster: staging
type: ProxyAddress


outbound defines a parameter for excluding traffic destined to certain addresses in the cluster from being routed to the cluster.

For example,

- cluster: ...


inbound defines the protocol used for tunneling requests to the local workstation. It can be one of xap or ssh. xap is a Signadot developped tunneling protocol and ssh uses the on-the-wire protocol that the ssh command uses for reverse tunneling.

For example,

- cluster: ...
protocol: xap

MacOS Considerations

MacOS Performance Bug

MacOS has a subtle bug with the performance of its packet filter pf when redirecting traffic, related to TCP segmentation offloading, which is an optimization to compute tcp segments on a network device instead of with the CPU.

By default, TCP segmentation offloading is on on MacOS. However when MacOS is configured to redirect traffic with pf, such offloading causes severe performance penalties, particularly in the latency of setting up TCP connections.

The Signadot CLI support for local workloads in sandboxes uses pf to redirect traffic and is impacted by this bug.

If you are seeing performance issues on MacOS traffic from a workstation to a connected cluster, the fix is to disable TCP segmentation offloading, which can be done as follows:

sudo sysctl -w net.inet.tcp.tso=0

However, the above command only disables TSO until the next reboot. We recommend turning off TSO permanently on the machine, since testing has shown no negative impact in doing so.

To turn off TSO permanently on MacOS create a file /Library/LaunchDaemons/sysctl.plist (or add to it):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "">
<plist version="1.0">

And then run

sudo launchctl load /Library/LaunchDaemons/sysctl.plist


On MacOS, if the cluster to which you'd like to connect is on a VPN which uses a network interface other than en0, you will need to specify the VPN interface in the CLI configuration:

- cluster: cluster-on-vpn
macOSVPNInterface: utun6

You can find the VPN interface on MacOS using ifconfig. It is typically a utunN interface which is up and has a peer defined. For example

% ifconfig utun6
utun6: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500
inet --> netmask 0xffffffe0