gravitational · ravicious · Oct 19, 2023 · Sep 29, 2023 · Oct 3, 2023 · Oct 3, 2023
diff --git a/docs/img/use-teleport/connect-cluster.png b/docs/img/use-teleport/connect-cluster.png
diff --git a/docs/img/use-teleport/connect-cluster@2x.png b/docs/img/use-teleport/connect-cluster@2x.png
diff --git a/docs/img/use-teleport/connect-my-computer-setup@2x.png b/docs/img/use-teleport/connect-my-computer-setup@2x.png
diff --git a/docs/img/use-teleport/connect-my-computer-status@2x.png b/docs/img/use-teleport/connect-my-computer-status@2x.png
diff --git a/docs/img/use-teleport/connect-my-computer-top-bar@2x.png b/docs/img/use-teleport/connect-my-computer-top-bar@2x.png
diff --git a/docs/img/use-teleport/connect-ui-overview.png b/docs/img/use-teleport/connect-ui-overview.png
diff --git a/docs/img/use-teleport/connect-ui-overview@2x.png b/docs/img/use-teleport/connect-ui-overview@2x.png
diff --git a/docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx b/docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx
@@ -0,0 +1,6 @@
+- A macOS or Linux device.
+- Teleport Connect v14.1+, on the same major version or one version behind the Teleport Proxy
+  Service version. See [version compatibility](../../faq.mdx#version-compatibility).
+- A local Teleport user: you must authenticate using credentials or passwordless login, and not with
+  SSO.
+- Permissions to create join tokens (verb `create` for [the `token` resource](../../access-controls/reference.mdx#teleport-resources)).
diff --git a/docs/pages/connect-your-client/introduction.mdx b/docs/pages/connect-your-client/introduction.mdx
@@ -126,7 +126,7 @@ server and database access within a single window.
 
 1. Browse and connect to all the resources your user is permitted to access:
 
-   ![An example of Teleport Connect, populated with instances](../../img/use-teleport/connect-ui-overview.png)
+   ![An example of Teleport Connect, populated with instances](../../img/use-teleport/connect-ui-overview@2x.png)
 
 ### Web UI
 

diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx
@@ -6,7 +6,7 @@ description: Using Teleport Connect
 Teleport Connect provides easy and secure access to SSH servers, databases, and Kubernetes clusters,
 with support for other resources coming in the future.
 
-![resources tab in Teleport Connect](../../img/use-teleport/connect-cluster.png)
+![resources tab in Teleport Connect](../../img/use-teleport/connect-cluster@2x.png)
 
 ## Installation & upgrade
 
@@ -46,7 +46,7 @@ $ "Teleport Connect Setup-(=teleport.version=).exe" /S
 
 ## User interface
 
-![user interface of Teleport Connect](../../img/use-teleport/connect-ui-overview.png)
+![user interface of Teleport Connect](../../img/use-teleport/connect-ui-overview@2x.png)
 
 The top bar of Teleport Connect consists of:
 
@@ -64,6 +64,174 @@ The top bar of Teleport Connect consists of:
 The **status bar** at the bottom displays **cluster breadcrumbs** in the bottom left, indicating
 which cluster the current tab is bound to, and the **Share Feedback** button in the bottom right.
 
+## Connect My Computer
+
+Connect My Computer makes it possible to add your personal machine to a Teleport cluster in just a
+couple of clicks.
+
+It is the easiest way to add a computer to the cluster, whether you're exploring the capabilities of
+Teleport or want your computer to be available in a Teleport-powered home lab.
+
+Connect My Computer sets up a Teleport agent managed completely by Teleport Connect, without having
+to use the terminal to get the job done and without the need for tools like `systemctl` to control
+the lifecycle of the agent.
+
+### Prerequisites
+
+(!docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx!)
+{/* The permission to read and update users is needed during setup but not for regular usage,
+that's why it's not listed in the partial. */}
+- Permissions to read and update user objects in the backend (verbs `read` and `update` for [the
+  `user` resource](../access-controls/reference.mdx#teleport-resources)).
+
+The agent runs as the current system user, not as root. Some features are thus not available, such
+as logging in as other system users or [host user creation](../server-access/guides/host-user-creation.mdx).
+
+### Setup and usage
+
+To begin the setup, click on the laptop icon in the top left and select "Connect My Computer". The
+new tab will guide you through an interaction-free setup. Click "Connect" to start the setup.
+
+![Connect My Computer in the top bar](../../img/use-teleport/connect-my-computer-top-bar@2x.png)
+
+The setup creates a new role in the cluster which grants access to your device as the current system
+user. The role is then added to your user object.
+
+<Admonition type="warning">
+The role is responsible merely for granting SSH access as your system user to the node managed by
+Connect My Computer. The node is subject to RBAC like any other SSH node in the cluster.
+
+In practice it means that users with administrative privileges can craft another role which grants
+access to the node or simply assign the Connect My Computer role to themselves.
+
+We recommend using Connect My Computer only in scenarios where no other user could plausibly gain
+access to the node, such as when exploring a Teleport cluster as its only user or in a home lab.
+</Admonition>
+
+Next, the setup downloads a Teleport agent for your platform and runs `teleport node configure`
+pointed at the current cluster. Once that is done, Connect My Computer starts the agent and waits
+for it to show up in the cluster as an SSH node.
+
+![Connect My Computer setup](../../img/use-teleport/connect-my-computer-setup@2x.png)
+
+After the agent joins the cluster, the tab transitions to showing the status of the agent. From
+here, you can connect to the node made available by the agent, stop and start the agent, as well as
+completely remove it. Manually logging out of the cluster will remove the agent as well.
+
+![Connect My Computer status](../../img/use-teleport/connect-my-computer-status@2x.png)
+
+Your computer will be shared while Teleport Connect is open. To stop sharing, close Teleport Connect
+or stop the agent through the Connect My Computer tab. Sharing will resume on app restart, unless
+you stop the agent before exiting. The agent stops immediately if Teleport Connect unexpectedly
+crashes.
+
+### Agent maintenance
+
+The version of the agent downloaded by Teleport Connect always matches the version of Teleport
+Connect. After upgrading Teleport Connect, Connect My Computer is going to automatically attempt to
+download a matching agent version before launching the agent.
+
+Connect My Computer always stores just a single version of the agent on disk.
+
+<Tabs>
+<TabItem label="macOS">
+The agent is stored at `~/Library/Caches/Teleport Connect/teleport/teleport`.
+</TabItem>
+<TabItem label="Linux">
+The agent is stored at `~/.cache/Teleport Connect/teleport/teleport` by default. The path respects
+`$XDG_CACHE_HOME`.
+</TabItem>
+</Tabs>
+
+### Troubleshooting Connect My Computer
+
+#### Accessing agent logs
+
+After the setup is done, open the Connect My Computer tab and from the three dots menu within the
+tab choose "Open agent logs directory".
+
+<Tabs>
+<TabItem label="macOS">
+The logs are stored at `~/Library/Application Support/Teleport Connect/agents/<cluster>/logs`.
+</TabItem>
+<TabItem label="Linux">
+The logs are stored at `~/.config/Teleport Connect/agents/<cluster>/logs`.
+</TabItem>
+</Tabs>
+
+#### The Connect My Computer icon is not visible in the top bar
+
+The icon is visible only if your setup satisfies the following requirements:
+
+(!docs/pages/connect-your-client/includes/connect-my-computer-prerequisites.mdx!)
+
+#### The Connect My Computer tab says that the agent is running, but the computer is not visible in the cluster
+
+Click "Connect" in the Connect My Computer tab. If the error message in the new tab says "access
+denied", it likely means that there's a role assigned to your cluster user which denies access to
+the Connect My Computer node, either by denying the specific login or access to the node itself
+through fields like `node_labels`. To resolve this problem, inspect the role list in the Management
+section of the Web UI. First, check what roles are assigned to your user object and then inspect
+each role. Look for a role with broad `deny` rules.
+
+If the error message mentions a node or a tunnel not being found, it means that while the cluster
+has a cached view of the agent, the agent did not join the cluster just yet. Wait for a couple of
+seconds and try connecting to the node again. If the problem persists, check [the agent logs](#accessing-agent-logs).
+
+#### Connect My Computer does not work after changing system username
+
+The system username that was in use at the time of configuring Connect My Computer is persisted in
+the Connect My Computer role for the given cluster user. To regain access to the Connect My Computer
+node, add the new system username under the `logins` section of the role. The role can be identified
+by its name following the format `connect-my-computer-<name of cluster user>`.
+
+Another solution is to [restart the setup](#restarting-the-setup).
+
+#### The agent cannot join the cluster and the logs say the token has expired or was not found
+
+In that scenario, the agent emits logs like these when starting up:
+
+```text
+INFO [PROC:1]    Joining the cluster with a secure token. pid:54364.1 service/connect.go:460
+INFO [AUTH]      Attempting registration via proxy server. auth/register.go:279
+ERRO [PROC:1]    Can not join the cluster as node, the token expired or not found. Regenerate the token and try again. pid:54364.1 service/connect.go:106
+```
+
+During the setup, Connect My Computer creates [a join token](../agents/join-services-to-your-cluster/join-token.mdx)
+that is valid for up to five minutes. If the logs say that the token has expired, it most likely
+means that the initial attempt to join the cluster has failed and you started another one after more
+than five minutes.
+
+To resolve this problem, remove the agent and [perform the setup again](#restarting-the-setup).
+
+#### Restarting the setup
+
+Since Teleport nodes are completely stateless, in case of problems with starting the agent or
+joining the cluster you may attempt to run the setup again. Either click "Retry" if the setup has
+failed or choose "Remove agent" from the three dots menu within the Connect My Computer tab after
+the agent was successfully configured.
+
+#### Preventing user access to Connect My Computer
+
+If you wish to prevent cluster users from using Connect My Computer, make sure they don't have
+permissions to create new join tokens. This is controlled by the `create` verb for the `token`
+resource. Either deny this permission explicitly or do not grant it in the first place. See [Access
+Controls Reference Documentation](../access-controls/reference.mdx#teleport-resources) for more
+details. Denying this permission will hide the icon in the top bar.
+
+Users who already set up agents will still be able to manage those agents, even after the denying
+them permissions to create join tokens. This is to ensure that a malicious admin is not able to make
+a user set up an agent and then lock the user out of removing the agent.
+
+To instantly revoke access to agents that have already joined the cluster, look for nodes labeled
+with the `teleport.dev/connect-my-computer/owner` label and then [place
+locks](../access-controls/guides/locking.mdx) on those nodes.
+
+```code
+$ tctl nodes ls -v --query='labels["teleport.dev/connect-my-computer/owner"] != ""'
+$ tctl lock --server-id=<Var name="Node UUID" /> --message="Using Connect My Computer is forbidden"
+```
+
 ## Connecting to an SSH server
 
 1. Open a tab with cluster resources by clicking on the plus symbol at the right end of the tab bar.