Set me up with an Android phone using Emuly.

- Emuly base URL: https://emuly.xyz
- Setup code: none. Start the device sign-in flow and give me the link to approve.
- Prompt version: 2026-11-21.2

## 0. Where you run

Find out, without asking me, where you run and where I sit. On Linux or macOS run:

```sh
uname -s; echo "ssh=${SSH_CONNECTION:-none} display=${DISPLAY:-}${WAYLAND_DISPLAY:-} t3=$(if [ -n "$T3CODE_THREAD_ID" ]; then echo yes; elif [ -d "$HOME/.t3" ]; then echo installed; fi)"
command -v tailscale >/dev/null && tailscale status --self --peers=false
```

On Windows, run this in PowerShell:

```powershell
"ssh=$(if ($env:SSH_CONNECTION) { $env:SSH_CONNECTION } else { 'none' }) session=$env:SESSIONNAME t3=$(if ($env:T3CODE_THREAD_ID) { 'yes' } elseif (Test-Path "$HOME\.t3") { 'installed' })"
if (Get-Command tailscale -ErrorAction SilentlyContinue) { tailscale status --self --peers=false }
```

- **Local:** no SSH connection. Links open on this computer.
- **Remote:** `SSH_CONNECTION` is set, or there is no display. On Windows, no display
  means `SESSIONNAME` is empty or `Services`; `Console` and `RDP-Tcp#N` have one. On macOS
  (`Darwin`), `DISPLAY` is not used: only `SSH_CONNECTION` means remote. I sit at another computer, so
  every link is for me to open there, and nothing here can open a window for me.
- **Over Tailscale:** remote, and the first address in `SSH_CONNECTION` is a Tailscale
  address (100.64.0.0/10). `tailscale whois <that address>` names my computer.

If your sandbox blocks the network (Codex does by default), ask me to approve network
access for your first Emuly `curl` instead of reporting an error.

- **In T3 Code:** `T3CODE_THREAD_ID` is set. Also set up the T3 Code Device panel (the skill says how).
- **T3 Code installed:** `t3=installed`. When the phone is ready, ask me once in this session:
  "You have T3 Code installed too. Do you want me to set it up so this phone shows in the
  T3 Code Device panel, next to your chat? (yes / no)". On yes, set it up (the skill says how).

Tell me in one line what you found, for example "You are on a remote Linux machine over
Tailscale from <computer>, so I will give you links to open there." The skill uses this.

## 1. Get a key

Fetch the setup commands for the OS you run on. If none matches, adapt the closest one.

If `uname -s` prints `Darwin`, you run on macOS: use the macos file.

  - linux: https://emuly.xyz/agent/setup/linux.md
  - macos: https://emuly.xyz/agent/setup/macos.md
  - windows: https://emuly.xyz/agent/setup/windows.md

Then follow the key steps at the end of this prompt.

## 2. Offer the emuly-playbook skill

The `emuly-playbook` skill tells you how to start, drive and stop Emuly phones.
Ask me once: "Should I install the emuly-playbook skill so I can run Emuly phones in later sessions?"

- **Yes, with npx** (needs Node.js): `npx skills add https://emuly.xyz -g -a <your agent id> -y`.
  Use your own agent id, for example `claude-code` or `cursor`.
- **Yes, without npx:** read https://emuly.xyz/.well-known/skills/index.json and download each file
  in `files` from https://emuly.xyz/.well-known/skills/emuly-playbook/<file> into your agent's user skills folder, keeping
  the paths. Claude Code: `~/.claude/skills/emuly-playbook/`. Codex: `~/.agents/skills/emuly-playbook/`. Cursor: `~/.cursor/skills/emuly-playbook/`.
  For another agent, use its documented skills folder.
- **No:** do not install anything. Fetch https://emuly.xyz/.well-known/skills/emuly-playbook/SKILL.md and follow it for this session only.

Install nothing without my yes. After an install, read the installed `SKILL.md`.

Keep every message to me at 3 short lines or fewer. Put the next action first.

## 3. Do the task

Follow the skill to choose or start a phone, to show it to me, and to fix errors yourself.
The skill lists the critical actions that need my yes. Follow that list exactly.

## 4. Tell me what you can do

Do this once, after setup is done and the first phone is ready. This one message may be
longer than 3 lines. Send this list, in these words:

> Your phone is ready. Here is what I can do with it:
>
> - **Use your app for you.** I tap, type, and scroll like a person.
> - **Install apps.** I can install an APK, or download a file to the phone.
> - **Take screenshots.** I can show you the screen at any time.
> - **Record videos.** I can record the screen, cut the video, and add short notes for each step.
> - **Test your app.** I can open your local app on the phone and check that it works.
> - **Make other phone types.** I can make a Pixel 9, a small phone, a Galaxy-size screen, or a tablet.
> - **Add videos to GitHub.** I can put a video in a PR or an issue.
>
> Just tell me what to do. For example: "Open my app and record a sign-up."

---

# Get an Emuly key

First check for a saved key: the `EMULY_KEY` user variable on Windows, or `EMULY_KEY` and
then `~/.config/emuly/key` on Linux and macOS. If one exists, skip this section.

The prompt either contains a setup code such as `emuly_sc_...` or it has no code:

- **Setup code in the prompt (A1):** exchange it once for a 90-day key with
  `POST /v1/agent/token` and body `{"code":"emuly_sc_...","name":"<agent> on <computer>"}`.
- **No setup code (A2):** start the device sign-in flow, show the user one short link, and
  wait for them to approve it in the browser.

Both return `key`, `expires_at`, `save`, `read` and `clear`. On Windows, `save` stores the
key in the user variable `EMULY_KEY`; run it once. On Linux and macOS, ignore those three and
save the key the way the OS file says. Never print the key in the chat.

### A2. Device sign-in flow

Run `POST /v1/agent/device`. It returns `device_code`, `user_code`,
`verification_uri_complete`, `expires_in` and `interval`. Show only the
`verification_uri_complete` link, on one short line:

> Approve this sign-in: https://emuly.xyz/link?code=WXYZ-2345

If you run on a remote machine (see "Where you run" in the prompt), say instead:

> Open this on your own computer and approve: https://emuly.xyz/link?code=WXYZ-2345

Ask the user to open it and approve the code. Then poll
`POST /v1/agent/device/token` with `{"device_code":"..."}` every `interval` seconds
(10 minutes maximum). Keep the device code in a variable, never in the chat.

- `authorization_pending`: keep polling.
- `slow_down`: wait 5 extra seconds, then keep polling.
- `access_denied`: stop. The user denied it.
- `expired_token`: stop. Ask the user to click **Copy prompt** again.
- Success returns the same body as `/v1/agent/token`. Save the key once and never print it.

### Later sessions and 401

Each new shell reads the saved key again; it is the only setup a later session needs. Never
exchange a second setup code unless the user clicks **Copy prompt** again in the console.

If a request that uses the saved key returns **401**, the key is expired or revoked:

1. Clear the saved key (the clear command in the OS file).
2. Ask the user to click **Copy prompt** in the Emuly console and send you the new code.
3. Exchange the new code once. Do not reuse the old code.

### Optional: check gh for links

Run `gh auth status` once and remember the result. Do not stop setup when gh is missing or
not logged in. A link (`emuly link`, see `references/local-servers.md` in the skill) uses gh
when it is logged in with the codespace scope. Without gh, the link uses the Emuly relay.
Do not install gh during setup.
