Install Boundary Desktop

Boundary end-users can use the Desktop Client app to connect to a running Boundary server to:

• Browse available targets
• Connect to targets
• Manage active sessions

Security administrators use the Boundary CLI and API to automate infrastructure access management, but the Desktop app makes Boundary accessible to low-code and no-code users. The browse, connect, and manage functionality is convenient for day-to-day operations.

In this tutorial, you will install the Boundary Desktop app, start Boundary in dev mode and connect to a target.

Prerequisites

1. A MacOS, Windows, or Linux Workstation
2. Boundary is still running in dev mode

Install Boundary Desktop

Boundary Desktop is available for MacOS, Windows, or Linux systems. Select the tab for your preferred OS.

$ brew tap hashicorp/tap

$ brew install hashicorp-boundary-desktop

Start a dev environment

Boundary Desktop connects with a running instance of a Boundary controller. In non-dev environments, Boundary Desktop would connect to this running controller without hosting it locally.

In this tutorial, you will deploy a Boundary controller locally using dev mode.

You already have a Boundary instance running in dev mode. If not, start it again.

$ boundary dev

Recall that Boundary starts in dev mode with default authentication credentials and a set of pre-defined resources.

These admin credentials enable you to log into the Boundary console.

• Generated Auth Method Login Name: admin
• Generated Auth Method Password: password

If you have any trouble getting dev mode to start properly, refer to the Start a Development Environment tutorial and then come back here.

Authenticate with Boundary Desktop

Next you will launch the Boundary Desktop app and connect it to the running controller.

1. Open the Boundary Desktop app installed earlier.

   You are prompted for the Boundary Cluster URL, which is the URL for the client to connect to the controller via the Boundary API. Running in dev mode, this will be http://127.0.0.1:9200

   

2. Select the Global scope. In non-dev environments you would select the scope you have access credentials for.

3. Select Generated global scope initial password auth method. In non-dev environments, you may have the option to select a different auth method.

4. Enter admin in the Login Name field.

   This is the Generated Auth Method Login Name.

5. Enter password in the Password field.

   This is the Generated Auth Method Password.

6. Click Sign In.

   

   You are presented with the Targets view, which contains a target generated using a direct address and a target generated using host sources. The Generated target with a direct address with the ID ttcp_1234567890 is the default target enabled by dev mode on your localhost.

   

Connect to a target

Next you will connect to the default target using the Desktop app.

1. Establish a connection

   Click on Connect next to the default target.

   The target's connection info is displayed. You can copy the connection details to your clipboard by clicking the buttons to the right of the Address & port or SSH fields.

   

2. Copy the target's connection details

   In this example, we are using SSH to connect. On the Details tab, select SSH and then click the copy button.

   

3. View the pending connection

   Navigate to the Sessions view using the sidebar on the left. Notice that the status for the Generated target has been updated to Pending.

   

4. Start an SSH session

   Select the ID of the target, and then select the >_ Shell tab. Paste the information you copied into the shell and run it. Enter your local administrator password when prompted to connect to the localhost target.

   

   Issues connecting or disconnects right after entering your password could be due to SSH restrictions on your local machine. Using System Preferences in MacOS, click Sharing, ensure that Remote Login is enabled, and check the Allow access for section to make sure that your user has the correct permissions to log in.

   Once connected, the Sessions view in the Boundary Desktop app should show the Generated target's status has been updated to Active.

   

5. Terminate the connection

   You can close the active session directly from the Boundary Desktop app.

   Under the Sessions view, click Cancel to the right of the status for the Generated target. The status will update to Canceling and a confirmation dialog should appear to verify the successful session termination.

   

6. Clean up

   Shutdown the dev environment by navigating back to the terminal session used to run boundary dev, and enter the ctrl+c keystroke to shutdown the dev server.

   ^C==> Boundary dev environment shutdown triggered
   T13:45:14.835-0600 [INFO]  worker: status ticking shutting down
   T13:45:14.836-0600 [INFO]  controller: recovery nonce ticking shutting down
   T13:45:14.836-0600 [INFO]  controller: terminating completed sessions ticking shutting down
   T13:45:14.836-0600 [INFO]  controller: status ticking shutting down
   $
   

Next steps

You installed the Boundary Desktop app, connected to a running controller and viewed and managed an SSH session using the app. The Desktop app is typically used for session management, while the Admin console is for administrative tasks like defining and managing Users, Groups, Roles, Projects and Host Catalogs.

The next step is to configure and manage targets that your organization wishes to protect. The recommended approach is to use Terraform to codify the Boundary configuration.