# How It Works
Source: https://docs.xtro.dev/how-it-works

Xtro's architecture and security model

Xtro lets you code on your Mac and continue on your iPhone. But how does your terminal session get from one device to another? This page explains the architecture and security model.

**The short version:** The relay server just moves your data between devices. It doesn't read it, doesn't store it, doesn't log it. We couldn't look at your code even if we wanted to.

## Three-Part Architecture

Xtro comprises three integrated components:

1. **Mac App (XtroMac)** - Runs on your Mac, hosts your terminal sessions, connects to VS Code, and transmits data to the relay server

2. **iOS App (XtroiOS)** - Runs on your iPhone/iPad, receives data from the relay server, and displays your terminal in real-time

3. **Relay Server** - Connects your Mac and iPhone across networks by routing messages between paired devices

```mermaid theme={null}
flowchart LR
    iOS[XtroiOS] <-->|WebSocket| Relay[xtro-relay]
    Mac[XtroMac] <-->|WebSocket| Relay
    Mac <-->|Local :8765| VS[VS Code]
```

## Why the Relay Server Exists

Your phone and computer are usually on different networks. They can't talk directly to each other.

Without the relay server, you'd need to:

* Configure port forwarding on your router
* Find your public IP address
* Hope your mobile network doesn't block incoming connections (spoiler: it does)

The relay server solves this by acting as a meeting point. Both your Mac and iPhone connect *out* to the relay server, which then routes messages between them. Think of it like an automated switchboard—both devices call in, and the switchboard connects them to each other.

## Security Model

### We Can't Read Your Data

Xtro uses two layers of encryption:

**Layer 1: The Tunnel (TLS)**
All connections to the relay use WSS (WebSocket Secure)—the same encryption that protects your banking. This prevents anyone on the network from snooping on your traffic.

**Layer 2: End-to-End Encryption**
Here's the important part: your terminal data is encrypted *before* it leaves your Mac, using a key that only your paired devices know. The relay server sees encrypted blobs and forwards them. It can't decrypt them. It doesn't have the key.

This means even if someone compromised our servers—whether a rogue employee, a hacker, or a state actor with a court order—they'd get nothing but encrypted gibberish. The relay terminates the TLS tunnel, but the payload inside remains encrypted end-to-end. We literally cannot read your data.

The server doesn't:

* Parse your terminal output
* Store your session content
* Log your commands
* Analyze what you're working on

It just sees "device A wants to send encrypted bytes to device B" and makes that happen. The relay is a dumb pipe—it routes data, nothing more.

**Don't take our word for it.** The relay server is \~1,500 lines of JavaScript, and we're open-sourcing it. Read every line yourself. You'll find no data collection, no logging, no decryption attempts. What you see is what you get.

### Same-Account Enforcement

Your devices can only pair with each other if they're logged into the same account. When your Mac generates a pairing QR code, the relay server validates that the iPhone scanning it belongs to the same user. Different accounts = pairing rejected.

### JWT Authentication

Every connection to the relay server requires a valid JWT token from Supabase. The server validates:

* Token signature and expiration
* User account status
* Active subscription

Invalid tokens are rejected immediately. No token = no connection.

### Subscription Validation

The relay server checks your subscription status on every connection. Active or trialing subscriptions work. Expired subscriptions get a 403 error. This happens server-side, so even a modified client can't bypass it.

### Message Routing Isolation

Messages are only routed between devices that:

1. Are explicitly paired (via QR code)
2. Belong to the same user account
3. Have active connections

The server validates user ownership on every message. If someone somehow got your device ID, they still couldn't receive your messages without your account credentials.

## Data Flow

When you type in your terminal:

1. **Mac receives keystroke** from VS Code or the native Mac terminal view
2. **Mac sends message** through the WebSocket connection to the relay server
3. **Relay validates** the sender's pairing and routes to the paired device
4. **iOS receives message** and updates the terminal display in real-time
5. **iOS sends ACK** back to confirm receipt (for connection health monitoring)

Terminal output flows the same way, just in reverse.

### Resilient Connections

Mobile networks are unreliable. Xtro handles this with:

* **Grace periods**: If your iPhone briefly disconnects (switching towers, entering elevator), the relay holds your session for 15 seconds before considering you offline
* **Automatic reconnection**: Apps automatically reconnect when network returns
* **Message queuing**: Important notifications queue up if you're offline and deliver when you reconnect
* **Ping monitoring**: The server detects zombie connections (WiFi died but socket didn't close) and cleans them up

## Local VS Code Integration

Beyond cloud relay, the Mac app also runs a local WebSocket server on port 8765. This lets the Xtro VS Code extension communicate directly with the Mac app without going through the internet—lower latency and works even offline.

## Open Source

The relay server is approximately 1,500 lines of JavaScript. We're open-sourcing it so you can:

* Audit the code yourself
* Verify our security claims
* Confirm there's no sneaky data collection

The code is straightforward: authenticate users, validate pairings, forward messages. No hidden complexity, no surprise features.

### Run Your Own Server

For those who are extra paranoid (we respect that), we'll provide everything you need to run your own relay server. Point your apps at your own infrastructure, and your data never touches our servers at all.

This is on our roadmap. When available, you'll be able to deploy with a single command to your own VPS, Docker host, or even a Raspberry Pi on your home network.

## Infrastructure

The relay server runs on Hetzner VPS in multiple regions:

* **USA (Ashburn)**: relay.xtro.dev
* **Singapore**: relay-sg.xtro.dev

Devices automatically connect to the nearest server for lower latency.

***

**Bottom line:** The relay server is a dumb pipe. It moves bytes between your devices and has no idea what's inside them. We don't read your code, we don't store your sessions, we don't analyze your terminal output. We just make the connection work—nothing more, nothing less.


# Introduction
Source: https://docs.xtro.dev/introduction

The world's first cross-device IDE front-end

**Start coding on your Mac, continue on your iPhone — exactly where you left off.**

Xtro synchronizes your development environment across devices. Your Mac runs the IDE (VS Code, Cursor, Windsurf) while your iPhone provides a full-featured mobile interface to interact with terminals, AI agents, source control, and more.

## Why Xtro?

AI coding agents like Claude Code, Cline, and Codex run long tasks—refactoring entire codebases, running test suites, deploying to production. You don't need to babysit them at your desk.

With Xtro, you can:

* Start a task on your Mac and walk away
* Get notified on your iPhone when the agent needs input or finishes
* Review diffs, approve changes, and continue the conversation—all from your phone
* Never miss an agent asking "Should I proceed?" while you're grabbing coffee

## Features

### Terminal Mirroring

Live terminal access from your Mac IDE. Execute commands, interact with AI CLI tools, and watch compilation output—all from your iPhone.

### AI-Agentic Workflows

* Voice-to-text prompting (minimize typing on mobile)
* Real-time notifications for agent completions, failures, and input requests
* Works with Claude Code, Cline, Gemini CLI, Codex, and more

### Source Control

Native Git integration:

* Stage/unstage files
* Create commits
* Manage branches
* Push/pull repositories

### Diff Viewer

Side-by-side code comparison with syntax highlighting. Review AI-generated changes before committing.

### Screenshot Uploads

Insert images directly from your photo library into AI agent conversations. Show the agent a bug screenshot, a design mockup, or an error message.

### Quick Keys

Single-tap shortcuts for common AI CLI commands. Bundled presets for:

* Claude Code
* Gemini CLI
* Cline
* Codex CLI
* Cursor Agent
* And more

## Supported IDEs

Xtro works with any IDE that has a terminal:

* VS Code
* Cursor
* Windsurf
* Trae
* Kiro

## Getting Started

1. Download **XtroMac** from [xtro.dev](https://xtro.dev)
2. Download **XtroiOS** from the App Store
3. Sign in with the same account on both devices
4. Scan the QR code to pair
5. Start coding

## Security

Your code stays private. Xtro uses end-to-end encryption—we can't read your terminal data even if we wanted to. Read our [How It Works](/how-it-works) page for the full security model.


# Quick Start
Source: https://docs.xtro.dev/quick-start

Get up and running with Xtro in under 5 minutes

## Requirements

* **macOS 15** Sequoia or later
* **iOS 18** or later
* A VS Code-compatible editor (VS Code, Cursor, Windsurf, Trae, Kiro, etc.)
* An active Xtro subscription

***

## 1. Create Your Account & Subscribe

Head to the [Xtro Dashboard](https://app.xtro.dev/dashboard) and create an account. You'll need an active subscription before using Xtro on any device — choose a plan that works for you.

***

## Mac Setup

### 2. Install XtroMac

Download the latest Mac app from your [Xtro Dashboard](https://app.xtro.dev/dashboard). Open the `.dmg`, drag to Applications, and launch it. Sign in with your account.

### 3. Install the IDE Extension

XtroMac automatically scans `/Applications` for VS Code forks, it reads each editor's `product.json` to identify Cursor, Windsurf, Positron, Trae, Kiro, and others. You'll see a list of detected editors with checkboxes. Check the ones you want, and XtroMac installs the Xtro extension into each.

Restart your editor(s) after installation.

### 4. Verify the Connection

Look for the **Xtro** button in the bottom-right of your editor's status bar:

* **Green**, connected to XtroMac
* **Orange**, disconnected (make sure XtroMac is running)

### 5. Create Your First Session

Click the Xtro status bar button in your editor. This opens a new terminal session that's synced through Xtro, accessible from your iPhone once paired.

***

## iPhone Setup

### 6. Install XtroiOS

Download **Xtro** from your [Xtro Dashboard](https://app.xtro.dev/dashboard) (it links to the App Store). Sign in with the same account you used on your Mac.

### 7. Pair Your Devices

On your Mac, click the Xtro menu bar icon and select **"Pair Device..."**. A QR code appears. Scan it with your iPhone's camera (or from within the Xtro iOS app). Once paired, the **Conversations** list populates with your active terminal sessions.

***

## Using Xtro

### Creating Sessions

You can create terminal sessions from either device:

* **From your editor**, click the Xtro status bar button
* **From your iPhone**, tap the **+** button (top-right on the Conversations list)

Sessions appear on both devices instantly.

### Terminal

Your iPhone shows a fully interactive terminal:

* **Double-tap** to bring up the keyboard
* **Swipe down** to dismiss the keyboard
* **Swipe left/right** to switch between sessions
* **Scroll up/down** to scroll the terminal buffer
* **Two-finger scroll** to scroll inside TUI apps (like OpenCode CLI) that normally require a mouse scroll wheel

### Quick Keys

The bottom bar provides single-tap shortcuts for common AI CLI commands (accept, reject, continue, etc.). Presets are bundled for Claude Code, Gemini CLI, Cline, Codex CLI, Cursor Agent, and more. You can customize these in Settings.

### Git Integration

Tap the branch icon to access source control:

* View commit history
* Browse diffs with syntax highlighting
* Stage/unstage files
* Create commits
* Push and pull

### Voice Input

Tap the mic icon to dictate. Your speech is transcribed and inserted directly into the terminal, useful for prompting AI agents without typing on a phone keyboard.

### Screenshot Upload

Tap the photo icon to pick an image from your library and send it into the active terminal session. Great for sharing bug screenshots, design mockups, or error messages with AI agents that support image input.

***

## Tips

* **Garbled TUI output?** Some terminal UIs (like OpenCode CLI) may render incorrectly on first load. Rotate your phone to landscape and back, this forces a re-render and fixes the layout.
* **Session persistence**, sessions stay alive as long as XtroMac is running. Close your laptop lid and reopen it, your sessions are still there.


# Relay Server
Source: https://docs.xtro.dev/self-hosting/relay-server

Run your own Xtro relay server

For those who want complete control over their data, you can run your own Xtro relay server.

<Note>
  Self-hosting is coming soon. This page will be updated with full instructions when available.
</Note>

## Why Self-Host?

The relay server is a "dumb pipe"—it routes encrypted messages between your devices without reading them. But if you want to be extra sure, you can run it yourself:

* **Complete control** - Your data never touches our infrastructure
* **Custom deployment** - Run on your own VPS, home server, or even a Raspberry Pi
* **Audit everything** - The code is open source and straightforward

## Requirements

* Node.js 18+
* A server with a public IP (or use a tunnel like Cloudflare)
* SSL certificate (required for WebSocket Secure connections)

## Quick Start

```bash theme={null}
# Coming soon
npx xtro-relay
```

## Docker

```bash theme={null}
# Coming soon
docker run -p 8080:8080 xtro/relay
```

## Configuration

Details coming soon.

## Pointing Your Apps to Your Server

Once your relay is running, you can configure the Xtro apps to use your server instead of the default `relay.xtro.dev`.

Instructions coming soon.