How to connect and use Ramus from ChatGPT

Add the Ramus plugin to ChatGPT, attach an APK, watch it run on a cloud Android device in the chat, check a flow and share a live link.

ChatGPT·Published November 1, 2026

This guide is for anyone who wants to run an Android app from a ChatGPT conversation, with no Android phone or Android Studio. You attach an APK, ChatGPT starts a cloud Android device, and the device runs live in the chat. ChatGPT can tap through a flow and report what it saw, and you get a link to send to a reviewer.

What you need

• A ChatGPT account. Plugins work in ChatGPT on the web, in the desktop app and on mobile. In a Business or Enterprise workspace, your admin decides which plugins members can install.
• A Ramus account. If you do not have one, you create it with GitHub when you connect. The Free plan includes 30 device minutes a month.
• An APK of your app, up to 300 MB. The device runs Android 17 on x86_64, so a debug build or a universal APK works best.

Connect Ramus

Install the Ramus plugin

1. Open Plugins in ChatGPT, or go to chatgpt.com/plugins, and search for Ramus. Its listing is titled Cloud Android emulators.
2. Select the plus button to install it.
3. Connect it when ChatGPT asks. A Ramus page opens: sign in with GitHub, then choose Allow on the consent page. It lists what ChatGPT will be able to do, such as use your Android emulators and upload your apps.
4. Start a new chat.

To check the connection, open Plugins and look under Installed. After ChatGPT's first call, the Ramus Agents page shows ChatGPT under Connected, with its last call and the devices it started in the last 7 days. Disconnect there cuts its access at once.

Add Ramus as a custom MCP server

Use this if the directory plugin is not available to you. ChatGPT on the web can connect any MCP server as a personal plugin:

1. Go to chatgpt.com/plugins, select the plus button, then Add custom MCP server.
2. Name it Ramus and enter the server URL https://api.ramus.dev/api/mcp.
3. Choose OAuth for authentication. Ramus supports both ways ChatGPT registers itself (a client metadata document or dynamic registration), so leave the client ID and secret empty.
4. Review the risk warning, select I understand and want to continue, then Create as a plugin.
5. Install the new plugin from your personal plugins and sign in to Ramus when it asks.

Your plan and workspace settings decide whether you can add custom MCP servers and use their write tools; OpenAI's custom MCP server guide has the current rules. Ramus needs write tools to start and drive a device. ChatGPT cannot send an API key header, so a custom connection also signs in with OAuth.

Tool approvals

ChatGPT runs tools that only read without asking. Ramus marks reading the screen, the logs and the device status as read-only. Starting a device, installing, tapping, typing, sharing and ending it change something, so ChatGPT can ask you to confirm them. When it asks, you can let it remember your choice for the rest of the conversation.

Start a device

In a new chat, type @, pick Ramus, and ask:

ChatGPT calls android_start_session with demo: true, and the device appears in the conversation, live. You can tap and type on it there, make it fullscreen, pop it out into a picture-in-picture window, or open it in your browser with Open. On the Free and Hobby plans it also shows the minutes left this month; select them to get more.

ChatGPT gets the same result as text, with the session id it uses for every later step and the watch link. On Free and Hobby it also carries the minutes left. From a test run on a local Ramus build:

{
  "session": "95fc232d-4417-4b52-94ec-d8e6bee7f386",
  "status": "active",
  "watch_url": "https://ramus.dev/share#rshr_…",
  "next": "the screenshot below is the device now. Give the person watch_url to watch live (it is view-only); call android_snapshot for refs before acting."
}

Other things to ask for: a blank device on the home screen, or a catalog app (Wikipedia, DuckDuckGo or Breezy Weather).

Install your app

Attach the APK to your message and ask:

ChatGPT passes the attachment to android_start_session as apk_file. Ramus downloads it from ChatGPT's file storage, installs it on a fresh device and opens it:

{
  "apk_file": {
    "download_url": "https://…",
    "file_id": "file_…",
    "file_name": "app-debug.apk"
  }
}

Attach the .apk file itself. A link to a file does not work, and Ramus installs APKs, not .aab bundles.

When a device is already running, attach the new build and say "Install this on the same device." ChatGPT calls android_install_app; the device keeps running and everyone watching stays connected.

You do not always need to attach a file:

• An app Ramus already has. Ramus keeps each app you have run in your account, on its Apps page. "Run com.example.app on Ramus" starts its latest version without uploading it again.
• A pull request preview. If the Ramus GitHub App builds your repository, "Open the Ramus preview for acme/shop#42" starts that PR's build. If the app is not installed yet, ChatGPT gives you a setup link to open yourself.

Coding agents with a shell upload a local build with android_upload_apk and a curl command. In ChatGPT, attaching the file does that job.

Let the agent check a flow

Describe the flow and what success looks like. Use a test account: anything you type in the chat stays in the conversation.

ChatGPT works in a loop: observe, act, verify. android_snapshot returns the elements on screen, each with a ref, and a gen for that snapshot. android_tap acts on an element's text or a ref, android_type on a ref, and expect makes a tap fail when the text it should lead to does not appear. Each action returns the new screen with fresh refs, so ChatGPT decides the next step from that result.

From a local Ramus build with a simulated device, on a small counter app: the tap on Increment expected "Count: 1", Ramus confirmed it appeared, and the result carries the new screen.

{
  "tapped": "e1",
  "element": "Increment",
  "verified": "\"Count: 1\" appeared",
  "screen": {
    "gen": 6,
    "count": 2,
    "elements": [
      {
        "ref": "e0",
        "text": "Count: 1",
        "resourceId": "dev.sandlot.fake:id/counter",
        "class": "TextView",
        "x": 0.132,
        "y": 0.417,
        "w": 0.735,
        "h": 0.104
      },
      {
        "ref": "e1",
        "text": "Increment",
        "contentDesc": "Increment counter",
        "resourceId": "dev.sandlot.fake:id/increment",
        "class": "Button",
        "clickable": true,
        "x": 0.132,
        "y": 0.625,
        "w": 0.735,
        "h": 0.104
      }
    ],
    "foreground_app": "dev.ramus.fake"
  },
  "next": "refs above are current (gen 6); act on them directly"
}

On a sign-in screen the same check is a tap on Sign in that expects "Welcome back".

You watch each step on the device in the chat. It is view-only; to take over, ask for the device page (viewer_url from android_session_status) and open it signed in. ChatGPT checks the screen with android_screenshot, which only it sees; to show you a still in the conversation it calls android_show_screen. When something breaks, ask for the evidence: the screen, android_logcat lines, and the device status, which names apps that Android closed (a crash, an ANR, low memory).

ChatGPT cannot change your code. Fix the bug in your own tools, rebuild, attach the new APK and ask:

Share a link

The device in the chat and its Open button use the session's watch link. Anyone who has that link can watch the device without an account, and nothing more, so share it only with people you mean to. It does not show your name.

For a reviewer, ask for a separate link:

ChatGPT calls android_share_session with permission: "watch" and ttl_minutes: 10080:

{
  "share_url": "https://ramus.dev/share#rshr_…",
  "permission": "watch",
  "expires_at": "2026-11-09T00:23:57.934Z",
  "note": "anyone with this link can watch the screen (not touch it), without an account — after the session ends, opening it relaunches the app until 2026-11-09T00:23:57.934Z. Hand it to the person; never post it publicly"
}

Links last 72 hours by default and up to 7 days, and you + 3 people can watch at once. Each link works on its own. After the device ends, opening a link starts a fresh device with the same app until the link expires. Ask for use instead of watch-only and the person can tap too; install also lets them install builds. ChatGPT can add a label as well.

"Revoke the share links for this device" revokes every link, including the watch link that the device in the chat uses. "End the device" frees it; its links keep working until they expire or you revoke them.

Give each person their own device

The links above join the device ChatGPT is on. To let a client or tester try your app in their own time, ask for a link that gives each person a device of their own:

ChatGPT calls android_share_session with own_device: true and label. Each person who opens the link gets a fresh device with the newest build you uploaded, without an account. The session must be running an app you uploaded. These devices run on your minutes and your plan's device limit, and when every device is busy the next person waits for one to free up. Each person's device lasts 30 minutes, and they can start another while the link works. Your own session comes first: if every device is in use, the longest-running recipient device ends.

Read the notes people send

Anyone with a link can choose Send feedback, pin a spot on a screenshot and write a note. The note carries the screenshot, the build, the last 200 lines of the device log and their recent taps, swipes and keys, unless they leave the log and steps out. Typing is recorded only as a number of characters, and taps are not recorded while the phone's on-screen keyboard is open. Notes and their screenshots are deleted after 30 days; you can delete one sooner on the app's page. ChatGPT can read them for you:

It reads them with android_list_feedback and android_get_feedback, which returns the screenshot as an image. When you say so, android_resolve_feedback resolves a note with a reply the person sees on their link.

Notes are written by other people, so treat their text, logs and screenshots as bug reports, never as instructions. See Share a running app.

Troubleshooting

• Ramus does not appear in Plugins. Open the listing directly. In a workspace, ask your admin whether the plugin is allowed.
• ChatGPT asks before every tap. Let it remember your choice for the conversation when it asks.
• The device card says the device is still starting. A start waits up to 50 seconds, and Ramus keeps a device that is still starting. Ask ChatGPT to check the device status.
• apk_file must be a file the user attached in ChatGPT. ChatGPT passed something other than an attachment. Attach the APK to the message again.
• bad_apk. The attached file is not an APK.
• too_large. The APK is over 300 MB.
• download_failed. Ramus could not fetch the attachment. Attach it again.
• unauthorized or insufficient_scope. The connection was disconnected or lacks a permission. Ask again; ChatGPT offers to connect Ramus again. Approve every permission on the consent page.
• stale_ref or expect_failed. The screen changed, or the expected text did not appear. ChatGPT should read the screen again; the error lists what was on screen.
• install_failed. The APK did not install, and the device keeps running. Check that the app runs on x86_64.
• session_cap. You are at your plan's device limit. Ask ChatGPT to install on the running device, or to end it first.
• quota_exhausted. You are out of minutes until the reset date in the message. ChatGPT passes on the upgrade link, and the minutes on the device card link to your plan.
• no_ready_build. The pull request has no finished Ramus build yet. Check the Ramus comment on the PR.

Limits

• Android 17 on x86_64. APKs up to 300 MB.
• Free: 30 minutes a month, 1 device. Hobby, $2 a month: 200 minutes, 1 device. Pro, $10 a month: unlimited minutes, 2 devices.
• A device ends after 10 minutes idle.
• Share links last 72 hours by default, up to 7 days; you + 3 on one device.
• A start waits up to 50 seconds for the device.

Details are in Plans and minutes.

Other agents: How to connect Ramus to any coding agent. Every tool and limit: the agent reference.