Connect with the Desktop Client or Client Agent

HCP Boundary end-users can use the Boundary Desktop app to connect to a running HCP Boundary instance to:

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

End users can also use the Boundary Client Agent to transparently connect to a target using their client of choice.

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. Users that establish sessions with targets frequently will also find the browse, connect, and manage functionality convenient for day-to-day operations.

In this tutorial, you will use the Boundary Desktop app or Boundary Client Agent to connect to a running target.

Prerequisites

To continue, you should have:

• Installed the Boundary binary.
• Installed the Desktop Client app and/or Client Agent.
• Access to an HCP Boundary instance.
• Completed the previous quick start tutorials.
• A publicly accessible Ubuntu instance used in the Connect to Your First Target tutorial.
• An ssh key-pair for authenticating with the Ubuntu instance.

Verify client installations

If you used the Boundary installer to set up the Boundary clients, then the Desktop Client app is already installed.

You can also connect to a target using Boundary's transparent sessions feature, which runs the Boundary Client Agent as a service to route session traffic through Boundary automatically. You should have installed the Boundary Client Agent using the Boundary installer.

You can also install the Desktop Client app manually instead of using the Boundary installer.

Refer to the Install Boundary tutorial if you need to install any of these components.

Connect with the Boundary Desktop Client

Try connecting to the target using the Boundary Desktop Client app.

Authenticate with Boundary Desktop

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

1. Open the Boundary Desktop Client app you installed earlier.

2. Enter the Boundary server Cluster URL and click Submit.

   You can retrieve this from the HCP Portal or run echo $BOUNDARY_ADDR from your terminal session.

3. Click Choose a different scope and select the Global scope.

4. Enter the administrator account in the Login Name field you selected when creating the HCP Boundary instance.

5. Enter the password you selected for the administrator account in the Password field.

6. Click Sign In.

   You are presented with the Targets view, which contains the targets created in the Connect to Your First Target tutorial.

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.

   You will be presented with a screen that displays the target's connection info. You can copy the connection details to your clipboard by clicking the buttons to the right of the Address & port or SSH fields.

   

1. 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.

   

2. 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.

   

3. 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.

   

4. Once connected, return to the Boundary Desktop and the Sessions view 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.

   

Connect using transparent sessions

If you have the Boundary Client Agent installed, you can route session traffic using transparent sessions and connect to targets using your client of choice. This workflow is useful for users who want to run Boundary in the background without needing to directly manage sessions.

The Boundary Client Agent runs locally on a client machine. When a user is authenticated to an HCP or Enterprise controller, the Client Agent checks all DNS requests against a list of targets the user has access to. If a target DNS is included in a request, Boundary automatically starts a session to the target and attempts to connect the client. This workflow allows users to interact with target aliases, instead of needing to copy resource IDs, names, scopes, and connection ports.

First, open a terminal session and check that the Client Agent is running:

$ boundary client-agent status

Status:
  Status:              paused
  Version:             0.1.2
  Recent errors:
    2025-01-24T12:20:01-07:00 - 20 DNS errors within 30 seconds,
    initiating pause

The Client Agent is paused when you are not authenticated to Boundary. Authenticate to start the Client Agent.

Set your HCP Boundary address.

$ export BOUNDARY_ADDR="https://YOUR_HCP_CLUSTER_ADDR"

Authenticate using your credentials.

$ boundary authenticate

Now check the status of the Client Agent again.

$ boundary client-agent status

Status:
  Address:
  https://83ea2ae7-f50b-4341-8938-xxxxxxxxxxxx.boundary.hashicorp.cloud
  Auth Token Expiration:   167h59m54s
  Auth Token Id:           at_ZX6WAtQF38
  Status:                  running
  Version:                 0.1.2
  Recent errors:
    2025-01-24T12:20:01-07:00 - 20 DNS errors within 30 seconds,
    initiating pause

Set the ubuntu target credentials in this shell session, or pass them directly to ssh.

$ export UBUNTU_USER=ubuntu_username UBUNTU_KEY=private_key.pem

With the Client Agent running, connect to the ubuntu target using ssh.

$ ssh ubuntu -l $UBUNTU_USER -i $UBUNTU_KEY
The authenticity of host 'ec2-xxx-xx-xxx-x.compute-1.amazonaws.com (xxx-xx-xxx-x)' can't be established.
ECDSA key fingerprint is l4UB/neBad9tvkgJf1QZWxheQpR59WgrgzEimCG6kZY.
Are you sure you want to continue connecting (yes/no)? yes

ubuntu@ip-172-32-88-177:~

Notice that you did not have to explicitly start a session with Boundary to connect to the instance. Boundary automatically detected the target's alias by checking its DNS and starting a session on your behalf. The session is terminated when you exit or stop the connection.

To learn more about managing the agent, refer to the Boundary Client Agent docs.

If you encounter any issues starting the session, check the list of available targets with boundary targets list, and then read the target details with boundary target read. If an alias is missing for the ubuntu-target, refer back to the Connect to your first target tutorial to learn about defining target aliases.

Next steps

You have completed the quick start series for HCP Boundary. Next, take a deeper dive into the various resources you created during this series such as scopes, targets, and host groups in the HCP Administration series.