Tractor Beam
Keeps a folder on your machine in continuous two-way sync with a Teleport
Beam. Work in the beam, keep the files on your laptop, delete the beam without
losing your work.
Prerequisites
- Beams access on a Teleport tenant, and
tsh 18.8 or newer. Teleport
Connect's bundled copy is found on macOS.
- VS Code 1.85 or newer, on macOS or Linux.
mutagen, which does the syncing, is downloaded on first use.
Setup
Install Tractor Beam from the VS Code Marketplace.
Log in to your beams tenant. The extension offers the login again whenever
it expires. Logging in through Teleport Connect does not count; tsh has
to write its own profile:
tsh login --proxy=<your-tenant>.beams.sh:443
Open a folder and click Tractor Beam in the status bar.
Usage
- Click the status bar item, or run "Tractor Beam: Start Syncing with Beam".
Accept the mutagen download if asked. A beam is created, the folder is
synced, and a terminal opens on the beam in the work directory. A new beam
takes a minute or two.
- Run
claude, codex or install and use pi in that terminal. Edit on either side; both
stay matched within a few seconds while the status bar shows code ✓.
During a large transfer it shows the progress instead, and "Resync now"
forces a cycle and reports when it is done.
- Click the status bar item for the menu: pause, terminal, resync, sync
rules, beam details, log, delete. Pausing leaves the beam and whatever runs
in it alone; deleting the beam keeps your local files.
If the status bar shows a conflict, something changed differently on both
sides, or a folder holding never-synced content such as .git was deleted on
the beam. The sync leaves your copy alone in that case. "Resolve conflicts,
keeping local" in the menu sends your files back to the beam without deleting
anything on your laptop.
Settings
| Setting |
Default |
Meaning |
tractor-beam.command |
bash -l |
What the beam terminal runs in the work directory. Set to claude, codex or pi to land directly in that agent. |
tractor-beam.proxy |
empty |
Beams cluster for the login offer, such as your-team.beams.sh. |
tractor-beam.region |
empty |
Region for new beams, such as us-west-2. Empty lets Teleport pick. |
tractor-beam.tshPath |
empty |
Path to tsh when it is not on PATH. |
tractor-beam.mutagenPath |
empty |
Path to mutagen when it is not on PATH and you do not want the downloaded copy. |
Sync rules
Sync rules live in mutagen.yml at the top of the synced folder, written on
first run and never overwritten. By default the whole folder syncs both ways,
the local side wins conflicts, and .git, node_modules, build output
(build, dist, target), .tractor-beam/, .env*, *.pem and *.key
never sync. To change what syncs, edit the ignore list through "Edit sync
rules" and start syncing again. Add .tractor-beam/ to the project's
.gitignore; it is per-person state.
mutagen is MIT licensed, copyright Mutagen IO, Inc. The icon glyph is
Microsoft's radio-tower codicon, MIT licensed; see
resources/ICON-CREDITS.md.
