Install Boundary clients

10min
|
HCP
Boundary

Boundary client tooling includes the CLI binary, the Boundary Desktop Client, and the Boundary Client Agent. Together they let you administer your HCP Boundary or Boundary Enterprise cluster and connect to targets. HashiCorp recommends using the Boundary installer, which installs all three components in compatible versions in a single step. This tutorial does not show how to compile Boundary from source, but you can learn more in the README.

We recommend using the following clients to get started with Boundary:

Boundary binary: The binary provides the command-line interface (CLI) tooling for connecting to Boundary targets, or administering a Boundary deployment.
Boundary Desktop Client app: The app provides a UI to browse and connect to available targets, manage sessions, and interact with targets using an embedded terminal.
Boundary Client Agent: Boundary's DNS agent runs alongside an authenticated Boundary client to enable transparent sessions. Transparent sessions allow users to switch from an active connection model to a passive connection model, and enable users who prefer to use their own client with the agent running as a background service to route session traffic automatically.

You can use the Boundary installer to install the Boundary binary, Desktop Client app, and Boundary Client Agent.

HashiCorp recommends that you use the Boundary installer to ensure compatible versions of the Boundary components are installed on your system. Refer to the Manual installation tab if you want to download the binary and Desktop Client separately.

The Boundary installer is available for macOS and Windows users. Select the tab for your system to continue.

Find the appropriate Boundary installer package for your system and download it. After you download the Boundary installer, execute the package installer.

Boundary installer dialog box

If you want to enable the Boundary Client Agent, you should select the Boundary Client Agent component during the installation:

Boundary installer components selection

Boundary runs as a single binary named boundary. Make sure that the boundary binary is available on your PATH. You can check the locations available on your path by running this command.

$ echo $PATH

Example output:

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

The output is a list of locations separated by colons. You can make Boundary available by moving the binary to one of the listed locations, or by adding Boundary's location to your PATH.

Tip

Permanently add a new location to your path by editing your shell's settings file (usually called something like ~/.bashrc, where the part of the file name after the . and before rc is the name of your shell). In that file you will see a line that starts with export PATH=, followed by a colon-separated list of locations. Add the location of the Boundary binary to that list and save the file. Then reload your shell's configuration with the command source ~/.bashrc, replacing bash with the name of your shell.

Find the appropriate Boundary installer package for your system and download it. After you download the Boundary installer, execute the package installer.

Boundary installer dialog box

If you want to enable the Boundary client agent, select the Boundary Client Agent component during the installation:

Boundary installer components selection

Boundary runs as a single binary named boundary. Make sure that the boundary binary is available on your PATH.

Tip

To add a location to your path using the GUI, navigate to Environment Variables in your system settings, and look for the variable called PATH. You will see a semicolon-separated list of locations. Add the Boundary binary's location to that list and then launch a new console window.

Install the Boundary Client Agent

You can use the Boundary Client Agent to set up transparent sessions, which allow Boundary to manage client connections in the background. This workflow is useful for users that want to a seamless experience using their existing client tooling.

Warning

You must install the Boundary Client Agent using the Boundary installer. Refer to the Boundary installer tab if you want to use Boundary with transparent sessions.

Install the Boundary binary

Select the tab for your operating system to manually install the Boundary binary.

You can install the macOS binary using Homebrew or by direct download.]

Homebrew is a free and open-source package management system for macOS. Install the official boundary formula from the terminal.

$ brew install hashicorp/tap/boundary

Note

This command installs a signed binary. It is automatically updated with every new official release.

To update to the latest, run

$ brew upgrade hashicorp/tap/boundary

To install Boundary, find the appropriate package for your system and download it. Boundary is packaged as a zip archive.

After downloading Boundary, unzip the package. Boundary runs as a single binary named boundary. Make sure that the boundary binary is available on your PATH. You can check the locations available on your path by running this command.

$ echo $PATH

Example output:

/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin

The output is a list of locations separated by colons. You can make Boundary available by moving the binary to one of the listed locations, or by adding Boundary's location to your PATH.

Tip

You can install the Windows binary through direct download or using Scoop. Windows Subsystem for Linux (WSL2) is recommended for Windows users running Boundary. You can find instructions under the Linux tab.

To install Boundary, find the appropriate package for your system and download it. Boundary is packaged as a zip archive.

After you download Boundary, unzip the package. Boundary runs as a single binary named boundary. Make sure that the boundary binary is available on your PATH.

Tip

Scoop is a free and open-source package management system for Windows. Install Boundary from the command-line.

$ scoop install boundary

Note

The Scoop main bucket repository is NOT maintained by HashiCorp. The latest version of Boundary is always available by direct download.

HashiCorp officially maintains and signs packages for the following Linux distributions.

Add the HashiCorp GPG key.

$ curl -fsSL https://apt.releases.hashicorp.com/gpg | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg

Add the official HashiCorp Linux repository.

$ echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/hashicorp.list

Update and install.

$ sudo apt update && sudo apt install boundary

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/RHEL/hashicorp.repo

Install.

$ sudo yum -y install boundary

Install dnf config-manager to manage your repositories.

$ sudo dnf install -y dnf-plugins-core

Use dnf config-manager to add the official HashiCorp Linux repository.

$ sudo dnf config-manager --add-repo https://rpm.releases.hashicorp.com/fedora/hashicorp.repo

Install.

sudo dnf -y install boundary

Install yum-config-manager to manage your repositories.

$ sudo yum install -y yum-utils

Use yum-config-manager to add the official HashiCorp Linux repository.

$ sudo yum-config-manager --add-repo https://rpm.releases.hashicorp.com/AmazonLinux/hashicorp.repo

Install.

$ sudo yum -y install boundary

Tip

Now that you have added the HashiCorp repository, you can install Terraform, [Consul](/consul tutorials/get-started-vms/virtual-machine-gs-deploy), Nomad and Packer with the same command.

Install the Boundary Desktop Client app

You can manually install the Boundary Desktop app on MacOS, Windows, or Linux systems. Select the tab for your preferred OS.

You can install the Boundary Desktop on MacOS manually using either:

The Homebrew package manager
Direct download

Homebrew is a free and open-source package management system for macOS. Install from the official Boundary Desktop cask from the terminal.

First, install the HashiCorp tap, a repository of all our Homebrew packages.

$ brew tap hashicorp/tap

Next, install Boundary Desktop with Homebrew:

$ brew install hashicorp-boundary-desktop

You can install Boundary Desktop on Windows using direct download of the zipped .exe application file.

Download the latest zipped copy of the .exe from the releases page.

Locate the downloaded boundary-desktop zip file and extract its contents
Open the unzipped Boundary/ folder and locate the boundary-desktop_<version>_.exe file. You may move the application file to your desktop, or your preferred location for quicker access
Double-click the boundary-desktop_<version>_.exe file to launch the Desktop application

Install Boundary Desktop

Boundary Desktop on Linux is currently only available as a .deb package. You can install by downloading the application file.

Download the latest .deb installer from the releases page.

On Debian systems either:

Right-click the downloaded .deb file and choose Kubuntu Package Menu -> Install Package

Open a terminal and point dpkg to the installer file:

$ sudo dpkg -i boundary-desktop_1.5.0_linux_amd64.deb

Install Boundary Desktop Linux

Verify the installation

After installing Boundary, verify the installation worked by opening a new command prompt or console, and checking that boundary is available.

Tip

If you receive an error that Boundary is not found, try logging out and logging back in to your system (this is necessary sometimes for Windows users).

$ boundary
Usage: boundary <command> [args]

Commands:
    accounts           Manage Boundary accounts
    auth-methods       Manage Boundary auth-methods
    auth-tokens        Manage Boundary auth-tokens
    authenticate       Authenticate the Boundary command-line client
    config             Manage resources related to Boundary's local configuration
    connect            Authorize a session against a target and launch a proxied connection
    database           Manage Boundary's database
    dev                Start a Boundary dev environment
    groups             Manage Boundary groups
    host-catalogs      Manage Boundary host-catalogs
    host-sets          Manage Boundary host-sets
    hosts              Manage Boundary hosts
    proxy              Launch the Boundary CLI in proxy mode
    roles              Manage Boundary roles
    scopes             Manage Boundary scopes
    server             Start a Boundary server
    sessions           Manage Boundary sessions
    targets            Manage Boundary targets
    users              Manage Boundary users

Verify the version of Boundary.

$ boundary version

Version information:
  Build Date:          2024-10-10T15:04:49Z
  Git Revision:        2e3fdb718cb5ed20017b124deb6f438310b9dd0f
  Version Number:      0.18.0

You have installed the Boundary clients! Continue to the next tutorial to continue learning about Boundary.

HCP Boundary vs Boundary Community Edition

Deploy an HCP Boundary cluster