Using Atom’s Teletype for Real‑Time Collaboration

Quick start: install and create a portal

If you need to edit the same Atom project with a teammate in real time, install the built‑in teletype package, generate a portal URL, and share it. Once both parties open the URL, cursor movements and typed text appear instantly in each editor.

Installation via command line

Open a terminal (you need write permission to your Atom packages directory, usually ~/.atom/packages). Run:

apm install teletype

The command downloads and activates the package. You can also install it through Settings → Install by searching for "teletype".

Creating and sharing a portal

1. Restart Atom if the package was just installed.
2. Look for the Teletype icon (two silhouettes) in the status bar at the bottom of the window.
3. Click the icon and select Create a portal. Atom contacts GitHub’s signaling service and displays a URL like https://teletype.atom.io/hub?portal=abcd1234.
4. Copy that URL and send it to your collaborator (via chat, email, etc.).
5. Your collaborator opens Atom, clicks the Teletype icon, chooses Join a portal, pastes the URL, and presses Enter.

After joining, both editors show each other’s cursors and any typed characters appear in real time.

How Teletype works under the hood

Teletype does not sync files on disk; it shares only the editor state (text, selections, scroll position) using a WebRTC peer‑to‑peer connection. The signaling phase—exchanging connection metadata—is handled by a GitHub‑hosted service over HTTPS. Once the signaling succeeds, the browsers (Atom’s embedded Chromium) establish a direct UDP/TCP flow for media‑like data, using STUN/TURN servers on ports 3478‑3481 to traverse NATs and firewalls. Only the signaling channel is encrypted; the actual edit data is sent unencrypted over the peer link, but it is ephemeral and not stored.

Verification and troubleshooting

To confirm that a peer connection was established:

1. Open Atom’s DevTools (View → Toggle Developer Tools).
2. In the Console tab, look for lines like ICE connection state: connected or ICE connection state: completed. If you see failed or disconnected, the WebRTC link did not form.
3. As a quick test, temporarily block outbound UDP/TCP ports 3478‑3481 on your firewall (e.g., using sudo ufw deny out 3478:3481 proto udp on Linux). Attempt to create a portal again; it should fail or hang, confirming the port requirement.
4. Restore the firewall rules after testing.

If the portal appears but you see no remote cursor, check that both parties have the teletype package activated and that no content‑security‑policy extensions are blocking WebSocket traffic to the signaling service.

Limits and common mistakes

• No persistent file sync: Teletype only shares the editor view. If a collaborator disconnects without saving, their unsaved edits are lost.
• Firewall/NAT issues: Outbound UDP/TCP 3478‑3481 must be allowed; otherwise portal creation fails.
• Encryption scope: Only the signaling messages are TLS‑encrypted; the edit stream itself is not. Do not rely on Teletype for confidential code unless you trust the network.
• Participant count: Performance degrades with latency or many users; more than ~5 simultaneous editors often introduces noticeable lag.
• Premature sharing: Trying to share a portal before the package finishes activating (e.g., immediately after Atom starts) can generate an invalid URL. Wait for the Teletype icon to become active.