# Telescope docs


---

# quickstart

A managed cloud VM for your project, on your phone. Your coding agent sets it up; you approve a few things.
## What you're setting up

Telescope gives each of your projects a **managed cloud VM that runs your whole stack**: the web app, its APIs, its workers. You open it from your phone, at real desktop size. Once it's set up, your day looks like this:

1. Ask your coding agent for a change, from your phone or anywhere.
2. The agent makes the change.
3. Open Telescope on your phone. The VM pulls the change and you see the running app.

Telescope is set up for Claude Code today. See [what's supported](supported.md) for the rest.

## Set it up

You need the repo cloned on your laptop and Claude Code installed. In Claude Code, add the Telescope plugin:

```
/plugin marketplace add frederickrohn/telescope-plugin
/plugin install telescope@telescope
```

Then, inside your repo, ask:

```
Set up this repo on Telescope
```

Claude takes it from there. It installs the `telescope` command (it asks first), signs you in, reads your repo to work out what needs to run, and starts your VM. You only step in for three things:

- **Approve what gets copied.** Claude shows you which env files it will send to your VM, by variable name only. Use dev or test keys here, since clicks on your phone are real.
- **Give Telescope read access to the repo.** The first time, a GitHub page opens. Pick **Only select repositories**, choose this repo, install, then press Enter in the terminal.
- **Add it to your phone.** A QR code opens at the end. Scan it, then in Safari tap **Share** → **Add to Home Screen**, with **Open as Web App** on.

The first setup takes a few minutes. Claude also offers two small things so your agent's work shows up:

- adding a short note to your repo's `CLAUDE.md`, so your agent's changes reach Telescope without getting in the way of your regular feature branches;
- checking that the Claude GitHub App can push to the repo.

If your app has sign-in, Claude tells you the one URL to add to your provider. See [your stack](your-stack.md).

## After that, just ask

The plugin also teaches Claude to manage Telescope for you. Say things like:

- "Delete the Telescope VM for my-app."
- "I changed my .env, update the preview."
- "Add my iPad to the preview."

More in [using Telescope](using.md).

## Without an agent

Prefer to run it yourself?

```bash
npm install -g usetelescope
telescope login
cd your-repo
telescope up
```

See [commands](commands.md) for everything else.


---

# using telescope

The toolbar on your phone, how syncing works, and what to ask your agent.
## Syncing

Your VM shows your agent's newest changes. It syncs when you open the app, when you switch back to it, and when you tap **sync**. Most changes show up in a second or two.

## The toolbar

Tap the small pill floating over your app.

| Control | What it does |
| --- | --- |
| Sync | Pull the newest changes now. |
| Branch | Follow the newest changes automatically, or stay on one branch. |
| Screen size | Laptop, 1440×900 (default), desktop, phone, or fit to your screen. |
| Keep warm | How long the VM stays awake after you leave, up to 30 minutes. |
| Sleep now | Put the VM to sleep right away. |

## Ask your agent

You rarely need to type a command. Ask your agent, and it runs the right one:

| You say | It runs |
| --- | --- |
| "Set up this repo on Telescope" | `telescope up` |
| "What Telescope projects do I have?" | `telescope ls` |
| "I changed my .env, update the preview" | `telescope env push` |
| "Add another phone" | `telescope link` |
| "Which devices can open my preview?" | `telescope devices` |
| "Remove my old iPad" | `telescope devices revoke` |
| "Delete the VM for my-app" | `telescope down my-app`, after checking with you |

## Another phone or tablet

Each device gets its own sign-in. Ask your agent to add one, or run `telescope link`. A QR code opens; scan it within 10 minutes. It works once. Devices stay signed in until they go 30 days unused.

## Sleep

VMs sleep when you're not looking and wake in a few seconds when you open the app. One VM is awake at a time, for up to 4 hours a day. See [help](help.md).


---

# what's supported

What we've tested, what should work, and how to tell us when your stack doesn't.
## Tested

These we've run end to end.

| Part | Tested with |
| --- | --- |
| Web app | Next.js 16, with npm |
| Backends | FastAPI, running next to the web app |
| Database | Hosted Supabase Postgres |
| Coding agent | Claude Code |
| Sign-in | Supabase Auth, Auth.js (GitHub and Google) and Clerk |
| Phone | iPhone (iOS 26), added to the home screen from Safari |

Sign-in providers all work the same way: add your VM's address to the provider once, and use redirect sign-in rather than popups. The ones above are the ones we've tried, not a list to choose from. See [your stack](your-stack.md).

## Should work

We haven't tried these, but nothing should stop them.

- **pnpm, yarn and bun** for the web app.
- **Other backends**: Express, Go, or anything else you start with a command. Your VM runs each one as its own service next to the web app.
- **Workers and job runners** that run as a process, like a queue worker or a scheduler.
- **Other coding agents**, like Codex. Telescope follows changes in your repo, so any agent that can make them should work. Setup is written for Claude Code today.
- **Other sign-in providers**, like PropelAuth or any hosted login that redirects back to an address you add.
- **Other hosted databases**, like Neon or Upstash.

## Not yet

- **Web apps that aren't Next.js.**
- **Docker**: databases and caches from docker-compose don't run on the VM. Use a hosted dev instance instead (Neon, Supabase or Upstash all have free tiers).
- **Popup sign-in.** Use your provider's redirect mode.

## Didn't work? Tell us

If setup fails or your app won't run, it's probably a stack we don't support yet, and we'd like to add it. Ask your agent:

```
Send Telescope feedback about what didn't work
```

It sends us what your stack is and what went wrong, without your code or secrets. That's how we decide what to support next.

## Off the map

Running a fancier setup? Agents in remote sandboxes, orchestrators that hand work between agents, background agents on a schedule: that's the new classic stack, and we haven't tried it with Telescope yet. We'd love to know how it goes.

Point it at a repo with Telescope set up and see whether the changes show up on your phone. Then tell us either way, through your agent as above, and include:

- which agents you run, and where (laptop, cloud, a sandbox service),
- what hands out the work (an orchestrator, a queue, a schedule),
- what worked and what didn't.

Whatever doesn't work yet, we'll use to decide what to build next.


---

# your stack

How your secrets get to your VM, and the one step sign-in needs.
## What runs

Your VM runs your project the way your laptop does: the web app plus any other processes it needs, each started with its usual command. Your agent works out which ones by reading the repo. For what we've tested and what should work, see [what's supported](supported.md).

## Env files and secrets

Your env files go from your laptop straight to your VM. Telescope passes them through and never stores them. To update them, edit the file on your laptop and ask your agent to update the preview (`telescope env push`). Deleting the VM deletes them too.

> **Careful**
> Everything on your VM is real. A button that calls a paid API spends real money when you tap it. Use dev or test keys with a spend cap, never production secrets.

## Sign-in

Sign-in providers only send people back to addresses they know, so add your VM's address once per project. Your agent gives you the exact URL. By provider:

| Provider | What to add |
| --- | --- |
| Supabase Auth | Redirect URL `https://<your-vm>/auth/callback**` |
| Auth.js | A callback `https://<your-vm>/api/auth/callback/<provider>`: for GitHub, a separate OAuth app; for Google, add it to the client's redirect URIs |
| Clerk | Nothing for dev instances; add the domain for production instances |

Use redirect sign-in, not popups; popups don't work on the phone.


---

# commands

The telescope command, for when you'd rather run things yourself.
## Install

```bash
npm install -g usetelescope
```

Needs Node 20 or later. Or skip the install and use `npx usetelescope <command>`.

## Commands

| Command | What it does |
| --- | --- |
| `telescope login` | Sign in. |
| `telescope up` | Set up or repair the VM for the repo you're in. |
| `telescope ls` | List your projects and their addresses. |
| `telescope link [project]` | Show a QR code to add a phone or browser. |
| `telescope devices [project]` | List devices; `telescope devices revoke <id>` removes one. |
| `telescope env push [project]` | Send your updated env files to the VM. |
| `telescope logs [project]` | Show your VM's logs. |
| `telescope down <project>` | Delete a project's VM and everything on it. |
| `telescope feedback "<message>"` | Tell us what didn't work. |
| `telescope whoami` / `logout` | Your account on this machine. |

## Setup details

`telescope up` reads a small config that says what to run: the app folder, which env files to copy, and any extra services with their start commands. Your agent writes it for you and Telescope stores it with the project, so nothing is added to your repo. Running `telescope up` again reuses it.


---

# help

Limits, and what to do when something looks wrong.
## Limits

- 3 projects per account.
- 1 VM awake at a time: opening another puts the last one to sleep.
- 4 awake hours a day, resetting at midnight UTC.

## Something looks wrong

| You see | Try |
| --- | --- |
| An old version of your app | Tap **sync**, and check your agent finished its change. |
| A blank or broken page | Ask your agent to repair the preview (`telescope up` in the repo). |
| Setup fails, or your stack won't run | Probably a stack we don't support yet. Ask your agent to send Telescope feedback; see [what's supported](supported.md). |
| Your agent can't push (403) | Install the Claude GitHub App on the repo. |
| Sign-in loops | Add your VM's address to your sign-in provider. See [your stack](your-stack.md). |
| A phone that no longer opens it | Add it again (`telescope link`). |
| An old home-screen icon | Remove the app from your home screen and add it again. |
| "You've used today's 4 preview hours" | Back after midnight UTC. Use **Sleep now** to save hours. |
| "Previews are paused right now" | Telescope is paused for a bit. Nothing to fix on your side. |
| "You can have up to 3 projects" | Delete one you don't use. |