
Directory Sharing is a Teleport feature of that makes it easy to move files between a local machine and a remote desktop—and apply changes to those files—without compromising security.
During a remote desktop session, you can select a folder on your local workstation to share with the remote desktop. Changes to the folder on either the remote desktop or your workstation are reflected on both machines for the duration of the session.
The shared directory makes it convenient to download log files, edit configuration files, or perform any other file manipulations on a remote Windows desktop. You can disable Directory Sharing for specific users via their Teleport roles, and use session recording to audit activity in the shared directory after the session ends.
Prerequisites
-
A running Teleport cluster. For details on how to set this up, see one of our Getting Started guides.
-
The
tctl
admin tool andtsh
client tool version >= 13.0.3.tctl versionTeleport v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see our Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 13.0.3, which you can download by visiting your Teleport account.tctl versionTeleport Enterprise v13.0.3 go1.20
tsh versionTeleport v13.0.3 go1.20
Please use the latest version of Teleport Enterprise documentation.
-
The Teleport Desktop Service with at least one remote desktop registered in your cluster. If you have not yet configured Desktop Access, read Getting Started with Desktop Access before beginning this guide.
-
A browser on your local machine that supports the File System Access API, which Teleport uses for Directory Sharing. We support the latest versions of Chromium-based browsers like Google Chrome, Brave, and Microsoft Edge.
Brave users can enable the File System Access API by navigating to brave://flags/#file-system-access-api and selecting "Enable".
You can see a full compatibility table in the Mozilla Developer Network documentation.
-
Make sure you can connect to Teleport. Log in to your cluster using
tsh
, then usetctl
remotely:tsh login --proxy=teleport.example.com [email protected]tctl statusCluster teleport.example.com
Version 13.0.3
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
You can run subsequent
tctl
commands in this guide on your local machine.For full privileges, you can also run
tctl
commands on your Auth Service host.
Step 1/4. Share a directory
To share a directory, open the Teleport Web UI and begin a desktop session by navigating to the "Desktops" tab on the sidebar, finding a desktop you want to connect to, and clicking "CONNECT".
Once the session starts, click the three-dot menu on the top-right of the screen and click "Share Directory":

Limitations on directories you can share
Prohibited directories
For security reasons the web browser's filesystem access API prohibits you from sharing certain directories, including the standard locations for commonly used user directories such as "Desktop" and "Documents", as well as critical directories more typically used by the operating system itself.
For a full list of the blocked user directories, see the File System Access Specification.
Subdirectories within these blocked user directories may still be shared.
Long directory names
Based on testing, we have determined that directory sharing leads to unexpected errors if you share directories whose names (including all path segments) have 640 characters or more.
After you share a directory
When you first share a directory, your browser will prompt you to allow it to make changes in the directory, and you will need to grant these permissions to enable directory sharing.
After you grant permissions, you will see a new directory in File Explorer on the remote desktop. The directory will have the same name as the directory on your local machine, but with "on teleport" appended to the name.

You can only share a single directory at a time.
Step 2/4. Edit files in your directory
You can easily share files—and file modifications—between your local machine and the remote desktop.
Editing on the remote side
When you create, edit, or delete a file in the shared directory on the remote side, your browser will apply those changes to the directory on your local machine.
If you move a file into the shared directory on the remote side, that file will appear on the local side as well. And if you move a file outside the directory on the remote side, the remote desktop will copy it, keeping it within the shared directory.
You can also copy a file from one subdirectory within the shared directory and paste it into another—the local side will reflect the changes.
Directory Sharing does not support moving files between subdirectories within the shared directory on the remote side.
Editing on the local side
You can create, edit, and delete files in the shared directory on your local machine, as well as move files between subdirectories.
To view your local changes on the remote side, you will need to either refresh or re-open the remote directory, or re-open any individual files you changed locally. When you do this, the remote desktop will request the current state of the directory from the Teleport Web UI.
File size restrictions
Performance for moving large files to and from the shared directory will depend on network conditions, and file editing performance will depend on the program you use to edit files.
While there is no size limit for files within your shared directory, we only recommend manipulating files up to 32 MB to reduce the impact of the shared directory on network bandwidth and system resources.
Step 3/4. Disconnect
To stop sharing a directory, end your remote desktop session. Navigate to the three-dot menu on the upper-right of the desktop session in your browser and click "Disconnect."
The next time you start a session on the remote desktop, the directory will no longer be shared. You will need to share the directory again to access its content.
Step 4/4. Disable Directory Sharing
The Teleport Auth Service grants access to Directory Sharing on a remote desktop based on the roles of the user who initiates the desktop session.
A Teleport role enables Directory Sharing by default. If one of a user's Teleport roles disables Directory Sharing, then Directory Sharing will be disabled for that user.
To disable Directory Sharing for a Teleport user, define a role similar to the
following in a file called role.yaml
:
kind: role
version: v5
metadata:
name: "no-sharing"
spec:
options:
desktop_directory_sharing: false
Create the role:
tctl create -f role.yaml
Assign the no-sharing
role to your Teleport user by running the following
commands, depending on whether you authenticate as a local Teleport user or via
the github
, saml
, or oidc
authentication connectors:
Retrieve your local user's configuration resource:
tctl get users/$(tsh status -f json | jq -r '.active.username') > out.yaml
Edit out.yaml
, adding no-sharing
to the list of existing roles:
roles:
- access
- auditor
- editor
+ - no-sharing
Apply your changes:
tctl create -f out.yaml
Retrieve your github
configuration resource:
tctl get github/github --with-secrets > github.yaml
Edit github.yaml
, adding no-sharing
to the
teams_to_roles
section. The team you will map to this role will depend on how
you have designed your organization's RBAC, but it should be the smallest team
possible within your organization. This team must also include your user.
Here is an example:
teams_to_roles:
- organization: octocats
team: admins
roles:
- access
+ - no-sharing
Apply your changes:
tctl create -f github.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to github.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your saml
configuration resource:
tctl get --with-secrets saml/mysaml > saml.yaml
Edit saml.yaml
, adding no-sharing
to the
attributes_to_roles
section. The attribute you will map to this role will
depend on how you have designed your organization's RBAC, but it should be the
smallest group possible within your organization. This group must also include
your user.
Here is an example:
attributes_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - no-sharing
Apply your changes:
tctl create -f saml.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to saml.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Retrieve your oidc
configuration resource:
tctl get oidc/myoidc --with-secrets > oidc.yaml
Edit oidc.yaml
, adding no-sharing
to the
claims_to_roles
section. The claim you will map to this role will depend on
how you have designed your organization's RBAC, but it should be the smallest
group possible within your organization. This group must also include your
user.
Here is an example:
claims_to_roles:
- name: "groups"
value: "my-group"
roles:
- access
+ - no-sharing
Apply your changes:
tctl create -f oidc.yaml
Note the --with-secrets
flag in the tctl get
command. This adds the value of
spec.signing_key_pair.private_key
to oidc.yaml
. This is a sensitive value,
so take precautions when creating this file and remove it after updating the resource.
Log out of your Teleport cluster and log in again to assume the new role.
Next steps
Further reading
Directory Sharing is a powerful tool for editing files on remote desktops, and you'll want to make sure you have a comprehensive audit trail so you can conduct a post-incident retrospective or investigate unintended usage. Learn how to set up session recording for desktop access.
Aside from Directory Sharing, the Teleport Desktop Service also enables you to share the contents of your clipboard with a remote desktop. Learn how to use Clipboard Sharing.
How Directory Sharing works
Directory Sharing involves a browser on a local workstation and a remote Windows desktop.
On the remote side, Directory Sharing takes advantage of file system-related messaging within the Remote Desktop Protocol (RDP). On the local side, the Teleport Web UI uses the browser's File System Access API to read from and write to a user-selected local directory.
The Teleport Web UI establishes a secure WebSocket session with the Teleport Proxy Service, which forwards traffic to and from the relevant Teleport Desktop Service instance.
The Teleport Desktop Service enables the Web UI to communicate with remote desktops by implementing Teleport Desktop Protocol (TDP), which creates an abstraction layer between the WebSocket protocol and RDP.
The Teleport Desktop Service converts TDP traffic from the Teleport Web UI into RDP traffic to send to the remote desktop. The Desktop Service also converts RDP traffic from the the remote desktop into TDP messages to send to the Teleport Web UI. Based on these messages, the Teleport Web UI advertises information about—or performs modifications on—the shared directory.
You can read more about TDP in Teleport RFD 37 and how Directory Sharing uses it in RFD 67.