How to connect and use Ramus from Claude Desktop and claude.ai

Add Ramus to Claude as a custom connector, sign in, and run, check and share Android apps on a cloud emulator from chat.

Claude Desktop and claude.ai·Published November 1, 2026

This guide is for people who use Claude in the chat app, on claude.ai or in Claude Desktop, and want it to try an Android app. At the end, Claude has a cloud Android device with your app on it, walks through a flow, tells you what it found, and gives you a link to watch or share. You take over from the device page.

You add Ramus once, as a custom connector. It then works in claude.ai, Claude Desktop and the Claude mobile apps. Chat has no terminal, so this guide also shows how your APK gets onto the device.

What you need

• A Claude plan that allows custom connectors: Free (one custom connector), Pro, Max, Team or Enterprise. On Team and Enterprise, an Owner adds the connector and each member connects their own account.
• A Ramus account. Sign in at ramus.dev with GitHub. Trial accounts cannot connect over MCP.
• An APK that runs on an x86_64 Android emulator, or a pull request with a Ramus preview build. The demo app needs nothing.

Connect Ramus

Add the connector

On claude.ai or in Claude Desktop:

1. Open Customize → Connectors (claude.ai/customize/connectors).
2. Choose Add custom connector.
3. Name it Ramus and enter the server URL https://api.ramus.dev/api/mcp.
4. If the dialog asks how to authenticate, choose Sign in now, and under OAuth client keep Use Claude's published identity. Add no request headers. If your dialog shows the name, URL and Advanced settings on one screen instead, leave the OAuth client ID and secret empty.
5. Choose Add, then Connect.

A Ramus page opens: Connect Claude to Ramus, published by claude.ai, returning to claude.ai. It lists what Claude will be able to do with your devices. Choose Allow.

Behind the scenes, Claude identifies itself with a Client ID Metadata Document that Anthropic hosts, and Ramus sends you back to https://claude.ai/api/mcp/auth_callback. No client registration is needed on either side. Register automatically works too: Claude registers itself with Ramus, and the consent page then says the app registered itself and its name is not verified.

On a Team or Enterprise plan

An Owner adds Ramus for the organization: Organization settings → Connectors, Add, Custom, then Web if asked, and the same URL. Each member then opens Customize → Connectors, finds Ramus with the Custom label, and chooses Connect to sign in with their own Ramus account. Owners can set each Ramus tool to Always allow, Needs approval or Blocked for everyone.

Some accounts also see Request headers in the dialog. It is a beta that sends a fixed credential on every request. To use a Ramus API key there, choose No sign-in and add the header authorization with the value Bearer rms_your_key_here, using a key from the API key tab on the Agents page. On Team and Enterprise, every member then shares that one Ramus account, its minutes and its devices, so use the sign-in unless that is what you want.

Claude Desktop, mobile and Claude Code

Connectors belong to your Claude account. Once Ramus is connected on claude.ai, it is there in Claude Desktop and in the Claude apps for iOS and Android. When Claude Code is signed in with the same claude.ai account, it lists the connector in /mcp too.

Claude Desktop also has a local file, claude_desktop_config.json (Settings → Developer → Edit Config). It starts MCP servers on your own computer. Ramus is a remote server, so it does not go there, and you need no local bridge.

Check that it connected

In a chat, open + → Connectors and check that Ramus is on. Connectors are switched on or off per conversation. To see the tools, open Customize → Connectors and select Ramus.

On Ramus, the Agents page lists Claude under Connected, with its last call, the devices it started in the last 7 days, and Disconnect.

Start a device

Ask Claude:

Claude asks before it calls a Ramus tool. You can allow it once or always. It calls android_start_session with demo: true. Ramus answers with the session id, a screenshot that Claude reads, and a watch link for you.

Open the link in your browser. You see the device live and can tap and type on it while Claude works.

Install your app

Claude in chat has no terminal, and it cannot pass a file you attach to a message on to Ramus. It also cannot use android_upload_apk, which returns a curl command for a terminal. Pick one of these instead.

Drop it on the device. Ask Claude for a blank device and a link to watch it:

Open the link and drop your APK anywhere on the page, or use the install button beside the screen. Ramus installs and opens it on that device. Tell Claude when it is done; Claude takes a snapshot and goes on from there. For each new build, drop it on the same page.

Start an app Ramus already has. An APK you uploaded on the dashboard, or with the CLI, stays in your apps. Ask Claude to start it by package name, such as "Start com.example.app on Ramus". android_start_session with app runs its latest version. Uploading on the dashboard also starts a device, so on a one-device plan, end that device first or ask Claude to use it.

Start a pull request preview. If the repository has the Ramus GitHub App, ask for "the Ramus preview for acme/app#42". Claude passes it as pr.

Let the agent check a flow

Give Claude the flow and what success looks like:

Claude works in a loop: observe, act, verify. android_snapshot returns the screen's elements, each with a ref, and a gen for that observation. android_tap names an element's text, or the ref and gen it came from, android_type names the ref and gen, and expect makes a tap fail unless the given text appears. Each action returns the new screen with fresh refs, so Claude decides the next step from that result.

From a local Ramus build with a simulated device, on a small counter app: Claude tapped Increment with expect: "Count: 1", Ramus confirmed the text 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"
}

When the text does not appear, the same call returns expect_failed with the text that was on screen.

A failed expect is a failed check. Claude collects evidence with android_screenshot and android_logcat, the device log. To see the screen yourself, open the watch link, or ask Claude to show it to you; it calls android_show_screen.

Claude cannot fix your code from a chat. It tells you what failed and where. Fix it, build, drop the new APK on the same device page, and ask Claude to run the check again. The device keeps running and everyone watching stays connected.

Share a link

The watch link from android_start_session is for you. Anyone who has it can watch the device without an account, and nothing more, so treat it like a password. It does not show your name. It lasts 72 hours, and you + 3 people can be on the device at once. After the device ends, opening the link starts a fresh device with the same app until the link expires.

For a reviewer, ask for a separate link:

Claude calls android_share_session with permission: "watch" and ttl_minutes: 10080, and gives you the share_url:

{
  "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"
}

Each link works on its own; the watch link keeps working. permission can also be use or install, the default, and label adds a note. To revoke one link, use Share on the device page in Ramus. android_share_session with revoke: true revokes every link of the session, the watch link included. android_end_session frees the device and leaves the links working.

Give each person their own device

The links above join the device Claude 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:

Claude 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. Claude 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

• There is no Add custom connector. On Team and Enterprise, only an Owner can add one; ask them. On Free, you may already have your one custom connector.
• Claude says it has no Ramus tools. Turn Ramus on for this conversation under + → Connectors.
• The Ramus page refuses the sign-in for a trial account. Trial accounts cannot sign in over MCP. Sign in to ramus.dev with GitHub.
• Claude shows "Authorization with the MCP server failed". Check that the URL is exactly https://api.ramus.dev/api/mcp. Authentication settings cannot be changed after you add a connector, so to try Register automatically, remove Ramus and add it again.
• Claude shows a Connect button in the chat. The Ramus sign-in expired or you disconnected Claude on the Agents page. Choose Connect and approve again; Claude retries the call.
• apk_file must be a file the user attached in ChatGPT. Claude tried to pass an attachment. Use one of the ways under Install your app.
• session_cap. You are at your plan's device limit, often because a dashboard upload started a device. Ask Claude to list your sessions and use or end one.
• stale_ref. The screen changed after that snapshot. Claude should take a fresh snapshot and find the element again.
• expect_failed. The tap was accepted but the expected text did not appear. The error lists what was on screen.
• install_failed. The APK did not install; the device keeps running. Check that the app runs on x86_64.
• quota_exhausted. You are out of minutes until the reset date in the message. Claude should stop and pass on the message and its upgrade link.
• Research used Ramus without asking. In Research, Claude calls connector tools without approval. Turn Ramus off for those chats.

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, from 60 seconds to 7 days; you + 3 people on one device.
• From chat, local APK upload, adb and the hot-reload loop are not available; use Claude Code or the CLI.

Details are in Plans and minutes.

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