> For the complete documentation index, see [llms.txt](https://docs.strongdm.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.strongdm.com/users/client.md). # StrongDM Client The StrongDM Desktop application (macOS and Windows) is the graphical component of the StrongDM client that is [installed](#installation/) on your local machine. The other component is the StrongDM [CLI Reference](/references/cli.md). Both the desktop app and the CLI allow you to authenticate to and use StrongDM to access resources. The desktop app features a single window that is used for logging in to StrongDM and for viewing all the resources available to you. ## StrongDM Desktop Application ### Authentication You can log in to StrongDM via one of the following methods. * **Email address or User ID:** To log in as a user, enter your email address or user ID, followed by your password. Select **Remember me** to avoid having to enter your email address for subsequent logins. * **Service Account:** To log in as a service account instead of a user, enter a token into the **Email address or User ID** field. Note that tokens are not remembered for subsequent logins. If an email address was previously remembered, that email is pre-populated on your next login. * **Single sign-on (SSO):** If your organization has SSO enabled, log in by entering your email address. Your web browser then opens and handles the rest of the authentication. Once authentication is complete, you will be redirected back to the desktop app. Your browser may ask you if it has permission to open the desktop app, unless you have disabled that behavior in the browser. Note that if SSO is enabled for your organization, you must log in via SSO unless you are a non-SSO user.
### Region After you enter your email address, a **Region** field may appear. The StrongDM control plane is available in multiple regions for organizations who wish to house their StrongDM instance in a different geographic location than the default (`US`). Switching to a non-default region when using the desktop is sometimes done by setting an environment variable (`SDM_APP_DOMAIN`). If the email you enter in the **Email address or User ID** field is present as a user on multiple control planes, and you do not have an environment variable set to indicate your region, the **Region** field is presented. Use it to choose which control plane you intend to log in to and use. ### User lock and unlock If your account is locked due to inactivity, the desktop app shows the locked screen. When locked, you cannot use the Resource Center to interact with resources. To unlock it, click **Unlock StrongDM** and authenticate to proceed. To lock your account, go to the **Account** menu and select **Lock**. When locked, the **Account** menu shows that your status is **Locked**, with a red dot beside it. ## Resource Center The Resource Center is the desktop app's main window that shows the following main areas: * **My Resources:** The resources that you can access * **Catalog:** The resources that you are eligible to request access to, if your organization has the Enterprise plan enabled * **Account information:** Your username and organization name (shown as the icon with your initials) * **Menu:** Desktop app actions and help options (shown as the three dots icon) {% hint style="info" %} The **Catalog** button is only visible to users whose organization has the Access Workflows feature enabled via the Enterprise plan. {% endhint %} The Resource Center is displayed when you launch the desktop app and log in to StrongDM, or (if you are already logged in) when you click on the **sdm** icon in the taskbar.
Changes in access grants are shown in real time. If you are unassigned from a role that provides access to PostgreSQL resources, for example, all such resources are immediately removed from your view in the Resource Center. If you do not have access to any resources, or if you have questions about what you can or cannot access, please ask your StrongDM administrator. ### Catalog The **Catalog** appears in the desktop app for organizations that have the Enterprise plan enabled. It provides a second button next to **My Resources**, allowing you to browse eligible resources and request access to them directly from the desktop app.
{% hint style="info" %} The **Catalog** button is only visible to users whose organization has the Access Workflows feature enabled via the Enterprise plan. If you do not see the **Catalog**, please contact your StrongDM administrator. {% endhint %} #### How to request access To request access to a resource, follow these steps: 1. Click the **Catalog** button at the top of the desktop app's Resource Center window. 2. Browse or search for the resource you need to access. 3. Select the resource and follow the prompts. First select your desired privileges from the dropdown.
4. Enter a reason for wanting access, set the desired duration (in days, hours, and/or minutes), and select your desired time and date(s) for access. 5. When done, click **Submit request**.
#### Pending requests After your request is submitted, it is considered pending. Your request is routed according to your organization's access workflow, which may include a review period and approval steps. Until access is granted, the resource you requested to access shows a **Pending** label and the **Select** button to request access to it is grayed out, as in the example shown.
### Move and resize The Resource Center window's width and height is adjustable to any size, and you can move it to any area of any screen. ### Dock icon For macOS the desktop app’s **sdm** icon is shown in the dock. For Windows, the blue **sdm** icon is shown in the tray and displays “StrongDM - Resource Center” upon hover. Click on it to open the Resource Center. You may right-click the dock icon or tray icon to reveal the following options: * **Open AdminUI**: This option opens the Admin UI (`https://app.strongdm.com`) in your web browser. * **Connect All**: Visible only when authenticated to StrongDM, this option allows you to connect to all assigned resources. ### Display of resources By default, resources are sorted by resource name. Each resource is shown with its host address and port number. The Resource Center shows up to 25 resources at a time and supports infinite scroll. If you have access to 100,000 resources, for example, you can scroll through all of them until you reach the end of the list.
### Connection to resources Click-to-connect capability lets you interact with a resource quickly. Simply click the Connect button beside any resource name to connect with the chosen resource immediately. Once connected, you can proceed to use your existing database, SSH, or RDP client to connect. ### Resource lock Resource locks ensure that a resource can be accessed by only one user at a time. Admins can require that you have a lock on a resource before you can access it, thus preventing other users from accessing it while it is locked. Some resources may only allow one session to be connected at a time, and a new session automatically disconnects an existing session. Resource locks prevent this scenario from happening. Moreover, some resources may need to be restricted to one session at a time for maintenance reasons or to prevent conflicts from concurrent users. When locked, the resource is unavailable for use by any other user. When unlocked, the resource is available to be locked and connected to if you are allowed to access it. In the Resource Center, you can see if a resource is locked and who locked it. When a resource is locked, a closed lock icon is shown next to the resource's name. Hover over that icon to view a tooltip indicating that the resource is locked, along with the name of the user or service account that locked it (for example, "Locked by Alice Glick"). When a resource is unlocked, an open lock icon is shown next to the resource's name. ### Port overrides By default, every resource that is created is assigned a port override value, which is the port that you use to connect to the resource through StrongDM. ### Websites The desktop app allows you to connect to any website resource with a single click. To open any website resource in your browser, first make sure you have already configured a [proxy](#connect/websites/). Then click the **connect** button next to the website resource name. ### Resource favorites You can save resources as favorites by opening the menu beside the resource name and selecting **Add to favorites**.
{% hint style="info" %} The ability to save resources is available in the desktop app only, not the CLI. {% endhint %} To remove a resource from your favorites, open the same menu beside the resource name and select **Remove from favorites**.
Favorite resources persist and remain as favorites even after you log out of or quit the desktop app. You can view a list of all favorite resources by clicking the **Favorites** tab at the top of the Resource Center. ### Resource search You can search for and display specific resources by name. The **Search** field recognizes partial strings, allowing you to type just part of a resource’s name to find matching resources. To return an exact match, encapsulate the resource name in quotation marks (for example, `"azure-gateway"`).
### Resource filters You can narrow the list of resources shown by clicking the filter button and selecting **Type**, **Health**, **Connection**, and/or **Tags** filters. * **Type** filters for resources of a specific type, such as Google Kubernetes Engine. The list shows all resource types that are currently present in the list of available resources. * **Health** filters for healthy or unhealthy resources. * **Connection** filters for resources that are connected (a local port is connected or open for that resource) or not connected (no ports are open for that resource). * **Tags** filters for resources that have specific tags assigned to them. You can type a tag name to find matching resources.
Once you have made your selection, those resources are displayed. To clear out your filter selection, you can click the "x" next to the filter you'd like to remove. ### Resource details To view additional information about a resource, open the menu beside the resource name and select **View Details**. The details panel shows information such as the resource's tags and an access summary.
## Desktop App Menu Options The button (three dots) at the top right corner of the desktop app's Resource Center window shows all the options available to you. When logged out of StrongDM, the button is called **About** and displays the following options. * [Versioning](#versioning) * **Help** * [Open app.strongdm.com](#open-appstrongdmcom) * [Documentation](#documentation) * [Quit](#quit)
When logged in to StrongDM, clicking the button (three dots) displays the following options. * **Actions** * [Connect all](#connect-all) * [Install sdm in PATH](#install-sdm-in-path) * [Update kubectl configuration](#update-kubectl-configuration) * [Reinstall StrongDM System Service](#reinstall-strongdm-system-service) * [Open app.strongdm.com](#open-appstrongdmcom) * **Help** * [Documentation](#documentation) * [Diagnostics](#diagnostics) * **About**: [Version numbers](#versioning) of the CLI and desktop app * [Quit app](#quit-app)
### Account information You can view your account information by clicking the icon with your initials at the top right corner of the desktop app. Account information includes your name, email address, and the name of your organization. There is also the option to **Log out** of StrongDM. ### Versioning The version number of your client (that is, the CLI) and desktop app are displayed in the format `Client: XX.YY.Z / App: XX.YY.Z`. Occasionally, you may be required to update to a higher version. When an update is available, the desktop app displays the **Update required** message. Updates do not happen automatically, so you need to select this option to update the desktop app. For detailed information about versioning, please see our [versioning information](#version/). ### Connect all The **Connect all** option lets you connect to all accessible resources simultaneously. Depending on your operating system, however, you may be limited in the number of resources to which you can connect. This limit is known as the file descriptor limit. Standard limits are as follows: * Linux-based: 1,024 resources * MacOS: 256 resources * Windows: 512 resources Note the following potential scenarios that may occur if you reach the limit for your OS: * If you run `sdm connect --all` and the number of resources you currently have access to is greater than the standard limit for your OS, the operation may fail. * If you run `sdm connect --filter` and the number of results for that filter is greater than the standard limit for your OS, the operation may fail. ### Install sdm in PATH Select **Install sdm in PATH** from the desktop app's menu to set up the StrongDM CLI in your system. You need to do this one time only, and a confirmation message will display when done.
Note that you may need to restart your terminal or Command Prompt. For detailed information about installing the CLI, please see the [installation guide](#installation/) for your particular operating system. ### Update kubectl configuration If cluster resources are available to you, the **Account** menu provides the **Update kubectl configuration** option. This option adds StrongDM-specific sections to your existing `~/.kube/config` file or creates a new one if it does not yet exist. Note that you need kubectl to be in your PATH before starting the desktop app and/or CLI in order for this option to work. You should see either a success message or an error message. If there is a conflict that prevents the completion of the kubeconfig update, you can choose to force the update. The error message displays the exact text of the configuration conflict. An example error message is shown below.
### Reinstall StrongDM System Service If Virtual Networking Mode resources are available for you to access, you must have the StrongDM System Service installed on your machine, in addition to the desktop app and/or CLI. The StrongDM System Service is installed via the PKG installer on macOS and via the EXE installer on Windows. If the StrongDM System Service is not installed, it can be installed (or reinstalled) by selecting the **Reinstall StrongDM System Service** option from the desktop app's **Actions** menu. ### Open AdminUI The **Open AdminUI** option opens the StrongDM Admin UI (`https://app.strongdm.com`) in your web browser. ### Documentation The **Documentation** option opens the StrongDM documentation in your web browser. ### Diagnostics The **Diagnostics** option uses the SDM Doctor Utility to check your system for potential problems. A new window launches, providing information that could be helpful if you need to troubleshoot or provide a copy of the output to Support.
The **Copy diagnostics** button lets you copy the diagnostic information to your clipboard. The **Reset StrongDM** button allows you to rename the current SDM configuration directory and create a fresh one. The **Help Center** button opens the StrongDM Help Center site in your web browser. At the Help Center, you can browse tutorials, read troubleshooting guides, and submit a request for help from StrongDM Support, if needed. Diagnostic information includes but is not limited to the following. | Diagnostic property | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | API | API ping rate (in milliseconds) | | Clock Drift | Clock drift (in milliseconds) | | CPU Load | CPU count and CPU usage | | Disk | Disk information | | DNS Configuration | Information about where the Admin UI, gateway, and relay resolve | | Environment Variables | Environment variables that are currently set | | File Descriptors | Maximum FD count | | File Permissions | Access information | | Gateway Connectivity | Link information and status | | Gateway Latency | Status and latency (in milliseconds) | | Gateway Link Redundancy | Information about redundant links | | GUI Version | Desktop app version number | | HTTP Proxy Settings | `HTTP_PROXY` and `HTTPS_PROXY` environment variables, as well as operating system proxy configuration (static proxy and PAC files) | | IP | Your IP address | | Local Network | Hostname and addresses | | Logs | Logs of your desktop app activity since you logged in | | Memory | Information about available memory and usage | | Metrics | Metrics that provide insights into the status of StrongDM nodes, including connection failures, disconnects, and availability | | Network | Network information, including hostname, interface, index, hardware address, flags, MTU, and addresses | | Network Quality | Latency and packet information | | Network Route Table | Routing information, including destination, gateway, metric, and interface | | OS Version | Operating system and architecture information | | RootCAs | Your certificates | | Runtime | StrongDM version number, hash, and build information | | Sessions | List of resources you are connected to | | TUN Status | Information about Virtual Networking Mode (VNM), if VNM is enabled and the StrongDM System Service is installed | | Uptime | Uptime (in minutes and seconds) | {% hint style="info" %} You can get the same diagnostics report in the CLI by running the `sdm doctor -v` command. {% endhint %} If the desktop app is in a bad connection state, the diagnostics window loads the last cached diagnostics information. If the desktop app is disconnected and then reconnected, the desktop app refetches the diagnostics. ### HTTP Proxy Support The desktop app supports dynamic HTTP proxies on Windows 10/11 and macOS. Proxy settings apply to all connections the client makes to the StrongDM control plane, and the client re-evaluates the proxy configuration dynamically (for example, when your VPN changes the proxy settings without requiring a client restart). The client selects a proxy in the following order, using the first one that is set: 1. Environment variables that are checked in the following order: `SDM_HTTPS_PROXY`, `sdm_https_proxy`, `HTTPS_PROXY`, `https_proxy` 2. Operating system automatic proxy configuration (PAC file) 3. Operating system static HTTP proxy {% hint style="info" %} The **Diagnostics** window now includes OS proxy information (both PAC-based and static) in addition to the `HTTPS_PROXY` environment variable values. {% endhint %} #### Proxy Cluster Health Status Resources that are accessed through a proxy cluster no longer display health check status indicators in the Resource Center. This behavior is enabled by default. ### Lock The Lock option is shown in the desktop app menu if MFA is enabled for your organization. Selecting the [Lock](#lock) option allows you to lock the desktop app on your computer. When locked, you are unauthenticated to StrongDM, your status is "Locked," and you cannot use the Resource Center. To use the desktop app again, you must unlock it. ### Log Out To log out of the desktop app, click the icon with your initials (at the top right corner of the desktop app), and then click **Log Out**. ### Quit app Click **Quit app** to close the desktop app. You remain logged in to StrongDM if you choose to use the CLI while the desktop app is closed. ## Multiple Sessions on Shared Workstations Multiple concurrent StrongDM sessions on a shared Windows workstation are not supported. If a user of a shared Windows workstation is using StrongDM and a second user of that workstation attempts to log in and use StrongDM at the same time, the second user is given an error that informs them that someone else is currently connected to StrongDM on that machine. ## Administering Users and Clients For StrongDM administrators looking to administer their users, or manage their fleet of client installs: * [Principals](/admin/principals.md) * [Clients](/admin/clients.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.strongdm.com/users/client.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.