Set up Android Backstage
Install the app on your phone, connect your AI assistant, approve phone access, then send one test. Plan on about ten minutes.
Before you start
- An Android phone on Android 11 or newer, connected to Wi-Fi
- The relay API key from the person who runs your relay
- For an assistant on a computer: Node.js 20 or newer on that computer. ChatGPT Work does not need it.
Install the app
On your phone-
Download Android Backstage
Open this page on your phone and tap the button. When you open the downloaded file, allow installs from your browser if Android asks.
Download the Android appAndroid 11 or newer
-
Open Backstage
It opens on Connect your assistant and asks for a connection code. Leave it there. You get the code in the next step.
Connect your assistant
On your computer, then your phoneWhich assistant are you connecting?
Steps for Codex
Do these steps on the computer where Codex runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent codex
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
Codex on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
Codex on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/codex/.
Steps for Cursor desktop
Do these steps on the computer where Cursor desktop runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent cursor
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
Cursor on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
Cursor on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/cursor/.
Steps for Cursor Cloud
Do these steps inside the cloud VM where your Cursor agent works, not on your laptop.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent cursor-cloud
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
Cursor Cloud. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
Cursor Cloudso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/cursor-cloud/.
Steps for Claude Code
Do these steps on the computer where Claude Code runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent claude
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
Claude Code on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
Claude Code on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/claude/.
Steps for Claude Desktop
Do these steps on the computer where Claude Desktop runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent claude-desktop
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
Claude Desktop on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
Claude Desktop on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/claude-desktop/.
Steps for VS Code / Copilot
Do these steps on the computer where VS Code / Copilot runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent vscode
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
VS Code on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
VS Code on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/vscode/.
Steps for Gemini CLI
Do these steps on the computer where Gemini CLI runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent gemini
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
Gemini CLI on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
Gemini CLI on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/gemini/.
Steps for OpenCode
Do these steps on the computer where OpenCode runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent opencode
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
OpenCode on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
OpenCode on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/opencode/.
Steps for ChatGPT Work
ChatGPT Work connects through a gateway on the computer that runs your relay. If someone else runs it, ask them to do the first step.
Get a connection code from the relay computer
On the computer that runs the relay, run:
backstage --config ~/.config/android-backstage/work/backstage.json pair --name phone --client-name "ChatGPT Work"
It shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
ChatGPT Work. Tap Connect assistant. The terminal finishes on its own.
Steps for Other MCP client
Do these steps on the computer where Other MCP client runs.
Download the agent kit
Extract the ZIP into a folder you will keep. The settings you generate later point at this folder.
Download the agent kitNeeds Node.js 20 or newer.
Run the setup helper
Open a terminal in the extracted folder and run:
node setup.mjs --agent generic
It asks four questions:
- Relay address
- Press Enter to use
https://relay.android-backstage.com, or type the address your relay owner gave you. - Relay API key
- Paste the key from your relay owner. It stays hidden while you type.
- Phone name
- Press Enter to call it
phone. - Client name
- Press Enter for
MCP client on this computer. Your phone shows this name.
The terminal then shows a connection code like
ABCD-EFGHJK. Keep the terminal open.Enter the code on your phone
In Backstage, type the code into Connection code. Under Connection name, type
MCP client on this computerso your phone shows what has access. Tap Connect assistant.The terminal finishes on its own and writes your settings into
generated/generic/.
Allow phone access
On your phoneAfter the assistant connects, Backstage shows Allow phone access. Stay on Wi-Fi for this step.
-
Turn on Wireless debugging
Tap Open Android settings. In Developer options, turn on Wireless debugging, then tap its name.
Can’t find Developer options?
Open Settings → About phone and tap Build number seven times, then enter your screen-lock PIN if asked. Some phones put Build number under Software information. Go back to Backstage and tap Open Android settings again.
-
Choose “Pair device with pairing code”
Android shows a 6‑digit code. Keep this screen open.
-
Enter the 6‑digit code in the Backstage notification
Pull down your notifications, tap Enter code on the Backstage notification, and type the six digits. You can stay in Android Settings while you do this.
No notification? Allow notifications for Backstage when it asks, or use split screen to show Backstage next to Settings and tap Enter the code in this app.
Finish in your assistant and send a test
On your computerShowing steps for Codex. Change assistant
Steps for Codex
Add Backstage to Codex
Add the generated [mcp_servers.android-backstage] section to your Codex config. Keep existing sections. Restart Codex or open a new task.
- Generated file
generated/codex/config.toml- Goes into
~/.codex/config.toml
Add only the Backstage entry. Keep everything else in that file. Codex documentation ↗
Add the phone skill
Copy
generated/codex/skills/phone/SKILL.mdto.agents/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for Cursor desktop
Add Backstage to Cursor desktop
Merge the generated mcpServers entry into .cursor/mcp.json. Open Cursor Settings → Tools & MCP, and enable Android Backstage.
- Generated file
generated/cursor/mcp.json- Goes into
.cursor/mcp.json in your project
Add only the Backstage entry. Keep everything else in that file. Cursor desktop documentation ↗
Add the phone skill
Copy
generated/cursor/skills/phone/SKILL.mdto.cursor/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for Cursor Cloud
Add Backstage to Cursor Cloud
Run setup inside the cloud VM, then merge the generated mcpServers entry into that VM’s .cursor/mcp.json. Keep the private client config out of Git and snapshots. Recreated VMs need secure state restoration or a new pairing.
- Generated file
generated/cursor-cloud/mcp.json- Goes into
.cursor/mcp.json inside the cloud project
Add only the Backstage entry. Keep everything else in that file. Cursor Cloud documentation ↗
Add the phone skill
Copy
generated/cursor-cloud/skills/phone/SKILL.mdto.cursor/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for Claude Code
Add Backstage to Claude Code
Merge the generated mcpServers entry into .mcp.json. Restart Claude Code, approve the server, then check /mcp. The generated Claude plugin is an alternative; use only one method.
- Generated file
generated/claude/.mcp.json- Goes into
.mcp.json in your project
Add only the Backstage entry. Keep everything else in that file. Claude Code documentation ↗
Add the phone skill
Copy
generated/claude/skills/phone/SKILL.mdto.claude/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for Claude Desktop
Add Backstage to Claude Desktop
Merge the generated mcpServers entry into the file opened by Edit Config, then fully quit and reopen Claude Desktop. A local MCP-capable desktop app is required; this is not a claude.ai web connector.
- Generated file
generated/claude-desktop/claude_desktop_config.json- Goes into
Claude Desktop → Settings → Developer → Edit Config
Add only the Backstage entry. Keep everything else in that file. Claude Desktop documentation ↗
Add the phone skill
Use the included phone rules as project instructions. The rules are in
generated/claude-desktop/skills/phone/SKILL.md.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for VS Code / Copilot
Add Backstage to VS Code / Copilot
Merge the generated servers entry into .vscode/mcp.json. Use MCP: List Servers to start and trust it, then enable its tools in agent chat. Copilot Agent Host uses .mcp.json instead; a portable config is also included.
- Generated file
generated/vscode/mcp.json- Goes into
.vscode/mcp.json in your workspace
Add only the Backstage entry. Keep everything else in that file. VS Code / Copilot documentation ↗
Add the phone skill
Copy
generated/vscode/skills/phone/SKILL.mdto.github/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for Gemini CLI
Add Backstage to Gemini CLI
Merge the generated mcpServers entry into .gemini/settings.json. Start a new Gemini CLI session and check /mcp.
- Generated file
generated/gemini/settings.json- Goes into
.gemini/settings.json in your project
Add only the Backstage entry. Keep everything else in that file. Gemini CLI documentation ↗
Add the phone skill
Copy
generated/gemini/skills/phone/SKILL.mdto.gemini/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for OpenCode
Add Backstage to OpenCode
Merge the generated mcp entry into opencode.json (or your existing opencode.jsonc). Restart OpenCode. Keep other settings and MCP entries.
- Generated file
generated/opencode/opencode.json- Goes into
opencode.json in your project
Add only the Backstage entry. Keep everything else in that file. OpenCode documentation ↗
Add the phone skill
Copy
generated/opencode/skills/phone/SKILL.mdto.agents/skills/phone/SKILL.md. If your assistant has no skills folder, paste its contents into the assistant’s instructions.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for ChatGPT Work
Add Android Backstage in ChatGPT
In ChatGPT, open Settings → Security and login and turn on Developer mode. Then open Plugins → Create app. Name it
Android Backstage, choose OAuth, and use this URL:https://relay.android-backstage.com/work/mcp
Already created it? Open the app and choose Install plugin or Connect. ChatGPT app documentation ↗
Approve the connection
ChatGPT opens a Backstage approval page. On the relay computer, run:
backstage-work-approve
Enter the code it prints on the approval page. The code works for ten minutes and is different from both phone codes.
Send a test
Start a Work conversation with Android Backstage enabled and send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
Steps for Other MCP client
Add Backstage to Other MCP client
Choose a local/stdio MCP server and use the command, args and env from the generated file. Some clients use a different outer JSON structure. Restart or refresh the server.
- Generated file
generated/generic/mcp.json- Goes into
Your client’s local MCP server settings
Add only the Backstage entry. Keep everything else in that file. Other MCP client documentation ↗
Add the phone skill
Use skills/phone/SKILL.md as the client’s phone instructions. The rules are in
generated/generic/skills/phone/SKILL.md.It tells the assistant to work quietly on a hidden display and to leave your screen alone.
Send a test
Restart the assistant or refresh its tools, make sure Android Backstage is enabled, then send:
Use Android Backstage on the phone named "phone". Read ro.product.model with a background command and tell me the result. Do not open or touch the screen.
If you named your phone something other than “phone” during setup, use that name. A working connection replies with your phone’s model.
After setup
Control access from your phone
Backstage’s home screen has Pause access for everything, and each connection has its own Pause, Rename, Limit to an app and Remove.
One connection per assistant
Every chat that uses a connection shares its access. To add another assistant or computer, tap Add connection and repeat steps 2 and 4.
After a phone restart
Open Backstage and tap Resume access. Some phones turn Wireless debugging off when they restart; turn it back on if Backstage asks.
Only connect assistants you trust
A connected assistant can run commands and use apps on your phone. Pause or remove it at any time.
Fix a problem
I don’t see Wireless debugging
Connect the phone to Wi-Fi and turn on Developer options (see step 3). Android 11 or newer is required. Phones managed by a workplace may hide this setting; ask whoever manages the phone.
The 6‑digit code expires, or no notification appears
Allow notifications for Backstage, then open a fresh Pair device with pairing code screen and leave it open. Enter the new six digits in the Backstage notification. Split screen with Enter the code in this app also works. This is not your assistant’s connection code.
The connection code doesn’t connect
Keep the terminal command running while you enter the code; it expires after ten minutes. Type the code exactly as shown, like ABCD-EFGHJK. If it expired, run the setup command again for a fresh code. Backstage uses the server printed with the code; tap Change server only if yours differs.
It was working, then stopped
Open Backstage on the phone. If access is paused, tap Resume access. After a restart, turn Wireless debugging on again over Wi-Fi. Check that the phone has internet and that the computer running your relay is on. Short network drops reconnect on their own.
My assistant has no Android tools
Check that the Backstage entry is in the settings file listed in step 4, then restart the assistant or refresh its tools and enable Android Backstage. The paths in that entry must exist on the machine where the assistant runs; a path on your laptop does not exist inside a cloud VM.
ChatGPT says the connection is blocked
Your account or workspace must allow Developer mode and custom apps. Use the exact URL from step 4. If the approval code expired, ask for a new one. If a workplace policy blocks custom tools, its administrator has to allow them.
A request timed out. Should I ask again?
The phone may have finished the action anyway. Ask your assistant to check the result before repeating anything that sends a message, buys something or installs an app.