{"token_count": 1715} # Protect Agentic GitHub Access with Teleport Beams Teleport Beams allow you to grant AI agents access to your GitHub repositories with restricted permissions that prevent their nondeterministic access patterns from unintentional changes. In this guide, you will set up Teleport RBAC to enable an AI agent to securely access a GitHub repository. ## How it works Teleport Beams are micro VM sandboxes for running agentic workloads, hosted on the Teleport Cloud infrastructure. When a user creates a beam, the Teleport Auth Service creates a **delegation session** that contains the user and their Teleport roles. An instance of the `tbot` daemon on the beam receives the ID of the delegation session and queries the Auth Service to issue a fresh Teleport identity to services that run on the beam. As a result, any agentic workloads running on the beam delegate the originating user's Teleport permissions. With Teleport RBAC, you can limit the permissions that agentic workloads have to access your GitHub repositories. You can configure your GitHub organization to use a Teleport certificate authority for authenticating users via SSH. Teleport then issues SSH certificates to users and proxies `git` commands to enforce RBAC. Users who create a beam can run AI agents on the beam to access repositories that belong to Teleport-protected GitHub organizations, as long as the users have permissions to access those organizations as well. ## Prerequisites - A Teleport Beams account. [Start your free trial](https://www.beams.run/). - A GitHub organization enrolled with Teleport. This guide assumes that you have followed [Proxy Git Commands with Teleport for GitHub](https://goteleport.com/docs/enroll-resources/application-access/cloud-apis/github-integration.md). While you may use a demo organization to follow this guide, it is up to you to configure access controls for users in the organization. Once a user authenticates to GitHub via Teleport as a particular GitHub user, they have all of the permissions you assigned to them in GitHub. - A role that can access your GitHub organization. You will have created this while setting up Teleport GitHub support. Teleport access controls for GitHub encompass an entire organization, so this will be the same role you will need to assign to your AI agent later in this guide. - Check that you can connect to your Teleport cluster and verify that you can run `tctl` and `tsh` commands using your current credentials. 1. Assign teleport.example.com to the domain name of the Teleport Proxy Service in your cluster and email\@example.com to your Teleport username. 2. Authenticate to your Teleport cluster. This depends on whether your shell is interactive or not. **In an interactive shell:** Run the following command. By default, this triggers a multi-factor authentication prompt: ``` $ tsh login --proxy=teleport.example.com --user=email@example.com $ tctl status Cluster teleport.example.com Version 19.0.0-dev CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678 ``` **On non-interactive environments:** If you are running `tsh` and `tctl` as an AI agent, in a CI/CD environment, or similar, make sure the `TELEPORT_IDENTITY_FILE` environment variable is assigned to a valid file path with credentials for your cluster. `tsh` and `tctl` read the file path from the environment variable and do not require a separate authentication step. If there is no identity file available, we recommend that you [set up Machine ID](https://goteleport.com/docs/machine-workload-identity/getting-started.md) to provision one automatically. When executing `tctl` commands with an identity file, you must pass the `--auth-server` flag to provide the Teleport Auth Service address, which is not included in the identity file. If you provide the Proxy Service address, `tctl` connects to the Proxy Service, which forwards traffic to and from the Teleport Auth Service. Update 443 to `3025` if you are contacting the Auth Service directly with `tctl`: ``` $ tctl status --auth-server=teleport.example.com:443 ``` For `tsh` commands that read an identity file, you must pass the `--proxy` flag, which points `tsh` to the address of the Teleport Proxy Service: ``` $ tsh status --proxy=teleport.example.com ``` Ensure client commands can access your identity file. Replace path/to/identity/file with the path to your identity file: ``` $ export TELEPORT_IDENTITY_FILE="${TELEPORT_IDENTITY_FILE:-path/to/identity/file}" ``` Add the `--auth-server` or `--proxy` flags to all subsequent `tctl` and `tsh` commands. If you can connect to the cluster and run the `tctl status` command, you can use your current credentials to run subsequent `tctl` commands from your workstation. If you host your own Teleport cluster, you can also run `tctl` commands on the computer that hosts the Teleport Auth Service for full permissions. ## Step 1/3. Configure Teleport RBAC You can enable an AI agent to access a Teleport-protected GitHub organization on a Teleport beam by configuring a user with access to: - create and access a beam - access your GitHub organization By following the Prerequisites of this guide, you will have already created a role that can access your GitHub organization. The preset `beam-user` role allows a user to create beams. 1. Create a user with both roles, assigning github-access to the role you created when enrolling your GitHub organization with Teleport and github-user to the name of your new user: ``` $ tctl users add \ --roles=github-access,beam-user github-user ``` 2. Follow the instructions in your terminal to activate your user. ## Step 2/3. Prepare your beam Create a beam and start an SSH session with it: 1. Authenticate to Teleport as the github-user user you created in the last step and enter your credentials: ``` $ tsh login \ --proxy=example.beams.sh \ --user=github-user ``` 2. Create a beam and access it: ``` $ tsh beams add ``` This command starts an SSH session with the new beam. Stay in the beam shell session for the next step. ## Step 3/3. Prompt your agent Prompt your agent to access your GitHub organization. 1. Start your LLM CLI. A beam initializes with `claude` and `codex` preinstalled. 2. Enter the following prompt, assigning repo-url to a repository URL within your protected organization: ``` Clone repo-url and summarize the last five merged PRs. ``` 3. Open the Teleport Web UI at example.beams.sh and navigate to **Audit** on the left sidebar. You should see an audit event similar to the following: ``` { "code": "TGIT001I", "event": "git.command", "time": "2026-08-11T14:32:07.000Z", "uid": "7699b806-e717-4821-85a5-d2f41acbe373", "user": "github-user", "service": "git-upload-pack", "path": "/" } ``` The `git.command` event type indicates the GitHub user responsible for a `git` command as well as the low-level protocol operation the user executed. In this case, we can see that the user invoked a read operation on the `git` server, `git-upload-pack`.