# Install a Border0 connector

Last validated Jul 6, 2026

> **Note:** Border0 + Tailscale is currently in beta.

You need to install a [Border0 connector][kb-border0-connectors] to provide secure sessions between a client and a protected resource on your Tailscale network, known as a tailnet.

You can choose between installing a connector from the Border0 admin portal or by installing a connector manually.

## Prerequisites

The following prerequisites are required for any device that you use to run as a Border0 connector.

* **Device compatibility**: The device must run either Linux or macOS.

* **Network reachability to Border0**: Your connector must have the ability to egress its network and reach the Border0 API and proxies through the internet.

* **Connector authentication**: Depending on your preferred installation method, you are required to create a connector token for the connector to authenticate. If you don't provide this token when required, the connector will not authenticate itself with your tailnet, preventing the connector from being online. Any socket that is associated only with this connector will not be available to your tailnet users.

The following prerequisites are use-case specific.

* **Network reachability to socket origins**: Your connector must be able to reach the target sockets (at the hostname and port configured in the upstream configuration) through the network, with the exception of AWS SSM targets. For example, if you have a connector running in a private network with no way of connecting to a target socket in a different private network, this connector will not be able to establish a connection to the upstream socket.

* **Third-party service authentication**: Depending on the upstream configuration of your connector's sockets, you may need additional credentials or configuration to authenticate against third-party services. Specifically, if any of the sockets are connected to by using the AWS EC2 Instance Connect or AWS SSM options, you need to make sure your connector's runtime has access to the appropriate AWS credentials that allow connecting with those methods.

  * For help with AWS credentials for connecting to AWS EC2 Instance Connect targets, refer to the [AWS credentials][xt-border0-aws-ec2] topic on the Border0 site.
  * For help with AWS credentials for connecting to AWS SSM targets, refer to the [AWS EC2 / ECS With SSM (Session Manager)][xt-border0-aws-ec2-with-ssm] topic on the Border0 site.

## Install the connector binary

The connector binary, `tailzero`, is a [`tsnet`][kb-tsnet] binary with a single auto-detecting installation script. `tailzero` provides the connector capability to let your users securely access sockets on your tailnet. How you install the connector binary depends on which platform you are using.

#### Linux/macOS

### Install with an invite code

Use an invite code if you want to download, create, and install the connector binary in one step. You can get an invite code from the Border0 admin portal.

1. In the Border0 admin portal, open the [**Connectors**][xt-border0-connectors-page] page.

2. Select **Add New Connector**.

3. Select the **Linux** option. Use the **Linux** option for macOS also.

4. Copy the command, replacing the placeholder with your actual invite code:

   ```shell
   sh <(curl -fsSL https://tailscale.border0.com/tailzero/install.sh) --invite <your-invite-code>
   ```

5. At a command prompt on the device that you want to use for the connector, run the command that you copied.

6. Follow the prompts to authenticate the device to your tailnet.

#### Docker

### Install with an invite code

Use an invite code if you want to download, create, and install the connector binary in one step. You can get an invite code from the Border0 admin portal.

1. In the Border0 admin portal, open the [**Connectors**][xt-border0-connectors-page] page.

2. Select **Add New Connector**.

3. Select the **Docker** option.

4. Copy the command, and replace the values for your particular needs:

   ```shell
   docker run -ti --name tailzero-connector \
   --volume tailzero-volume:/var/lib/tailzero \
   ghcr.io/borderzero/tailzero \
   --border0-invite-code <your-invite-code>
   ```

5. At a command prompt on the device that you want to use for the connector, run the command that you copied.

6. Follow the prompts to authenticate the device to your tailnet.

#### Kubernetes

1. In the Border0 admin portal, open the [**Connectors**][xt-border0-connectors-page] page.
2. Select **Add New Connector**.
3. Select the **Kubernetes** option.
4. Specify values for the namespace and release name. You can optionally choose to create the namespace.
5. At a commend prompt on the device that you want to use for the connector, run the commands that are shown in the **Launch New Connector** page.

#### AWS EC2

1. In the Border0 admin portal, open the [**Connectors**][xt-border0-connectors-page] page.
2. Select **Add New Connector**.
3. Select the **AWS EC2** option.
4. Follow the instructions that are shown in the **Launch New Connector** page.

This starts the connector process as a system service on your operating system, ensuring it runs after reboots. In the **Connectors** page, your connector should appear as **online**.

Once installed, you can create sockets, which will appear in your Tailscale client, letting your tailnet users securely access them without requiring an additional login on the client.

## Install the connector binary using advanced mode

If you want to control more aspects of connector installation, you can manually create a connector and a connector token (which is different from an invite code).

1. In the Border0 admin portal, open the [**Connectors**][xt-border0-connectors-page] page.
2. Select **Add New Connector**.
3. Select **Advanced**.
4. On the **Configure Connector** page, provided a name. The name must contain only lowercase letters, numbers, or dashes.
5. (Optional) Provide a description for your connector.
6. (Optional) Enable the built-in SSH service for the connector, which lets you connect to the connector itself over SSH as a service from your tailnet.
7. Select **Submit**.

Next, create a token that you will use for authentication.

1. Select **Create connector token**.
2. On the **New Connector Token** page, provide a name for the token. The name must contain only lowercase letters, numbers, or dashes.
3. Select an expiration value.
4. Select **Submit**.
5. Select **Copy Token** to place the token value in your clipboard buffer. Keep this value secure, as it can authenticate a device to your tailnet.

At a command prompt on the device that you want to use for the connector, run the `tailzero start` command. You can run either a one-off connector, or run the connector as an installed service.

To run a one-off connector, run the following command:

```shell
tailzero start \
--border0-token "${<your-connector-token>}"
```

To run the connector as an installed service:

```shell
sudo tailzero install \
--border0-token "${<your-connector-token>}"
```

## Manage the connector service

You can use the command line to manage the connector service.

### Manage the connector service on Linux

To check the current status of the Border0 connector service:

```shell
sudo systemctl status tailzero
```

To stop the Border0 connector service:

```shell
sudo systemctl stop tailzero
```

To start the Border0 connector service:

```shell
sudo systemctl start tailzero
```

To restart the Border0 connector service:

```shell
sudo systemctl restart tailzero
```

To check the connector logs:

```shell
journalctl -fu tailzero
```

### Manage the connector service on macOS

To stop the Border0 connector service:

```shell
sudo launchctl unload /Library/LaunchDaemons/tailzero.plist
```

To start the Border0 connector service:

```shell
sudo launchctl load /Library/LaunchDaemons/tailzero.plist
```

## Update the connector binary

You have two ways to update the connector binary.

You can run the `tailzero version upgrade` command:

```shell
sudo tailzero version upgrade
```

Alternatively, for Linux and macOS, run the same command as used to install the binary:

```shell
sh <(curl -fsSL https://tailscale.border0.com/tailzero/install.sh)
```

To determine which version you are running, run:

```shell
tailzero version
```

## Configure your connector

Once you have installed and started your connector, it should show up in the [**Connectors**][xt-border0-connectors-page] page. The connector provides several built-in services that can be enabled or disabled by configuring the connector details. By default the connector is configured to run a built-in SSH server, which lets you open an SSH shell on the connector host.

For more information about connectors, refer to [Border0 connectors][kb-border0-connectors].

[kb-border0-connectors]: /docs/border0/connectors

[kb-tsnet]: /docs/features/tsnet

[xt-border0-aws-ec2-with-ssm]: https://docs.border0.com/docs/aws-ec2-with-ssm#aws-credentials-for-border0-connector

[xt-border0-aws-ec2]: https://docs.border0.com/docs/aws-ec2-instance-connect#aws-credentials

[xt-border0-connectors-page]: https://portal.border0.com/connectors