Ramus Android

Give your coding agent a running Android app to inspect. The Ramus CLI can start an emulator, read the screen, tap, type, and capture evidence. It requires Node.js 22 or later.

Start with a trial

Run these commands to open the demo app without an account:

npx ramus-cli trial
npx ramus-cli session start --demo --wait

To test your own build, replace the second command with:

npx ramus-cli session start --apk app-debug.apk --wait

The trial stores a temporary key locally and lasts 60 minutes. It allows one active session and APKs up to 150 MB. GitHub previews and local development tunnels require a signed-in API key.

npx resolves the package against the npm registry on every invocation, which adds roughly 5–8 seconds per command. For repeated use, install it once with npm i -g ramus-cli and run ramus directly; the commands are otherwise identical.

Open the returned watchUrl to follow along or take control in your browser. If it is missing, run npx ramus-cli session share. Anyone with this link can operate the app, so share it only with intended reviewers. See Preview sessions for expiry and relaunch behavior.

Verify a flow

Observe Read the screen.
Get fresh refs.

Act Tap, type, or swipe
on what you found.

Verify Check the result
against your goal.

Observe again before the next action

Observe, act, verify. Read a snapshot and its ref/gen values, act on that observation, then check the result. Repeat with fresh references for the next action. An accepted tap alone does not prove the flow worked.

Start with an observation:

npx ramus-cli snapshot

The result includes visible elements with ref handles and a gen counter. Use values from that result for your next action. For example, if it shows a clickable e3 at generation 1:

npx ramus-cli tap e3 --gen 1 --expect "Welcome"

Replace the expected text with the outcome you want to check. Take a fresh snapshot before choosing another action; old references expire after an accepted action or a later snapshot.

• Use type "hello" --ref <ref> --gen <gen> to focus a field and enter text. Check the returned verified value and observe the result.
• Use wait --text "Welcome" for a specific state, or wait --stable after navigation.
• Capture evidence with screenshot --out screen.jpg. If the UI tree is incomplete, inspect the screenshot and use normalized coordinates, such as tap 0.5,0.72.
• Read logcat --limit 200 after a crash. Use app launch to return to the app.

Prefix these commands with npx ramus-cli. Commands use the most recent session unless you pass --session <id>. End a session with npx ramus-cli session end when everyone is finished.

Connect your agent

To use a device already open in your account, choose Connect to agent in the device page header. Configure an API key from the same account in your agent's environment, then copy the Agent prompt. It includes the current session ID and commands that inspect that device. The MCP tab provides the server URL and instructions for an MCP client. Copying instructions does not connect an agent; its first successful observation confirms the connection.

Anonymous share links grant browser access only. Connecting through the CLI or MCP requires an API key belonging to the device's owner.

Ask your agent to read ramus.dev/agents.md, then give it the APK path and a specific flow to verify. Ask it to report what it observed and include a screenshot and the watch link when available.

For Claude Code, save the android-use skill as .claude/skills/android-use/SKILL.md in your project, or clone it from github.com/ramus-dev/android-use. Other agents can use the same workflow through the CLI.

Clients without shell access can use the remote MCP server at https://api.ramus.dev/api/mcp. See the agent reference for authentication and supported tools. Uploading a local APK and running a development tunnel require the CLI.

Use your account

Create an API key in Settings and set RAMUS_API_KEY in the environment where your CLI or agent runs. Keep the key out of chat and URLs. Run npx ramus-cli status to check authentication and active sessions.

For a ready GitHub preview build:

npx ramus-cli session start --pr owner/repo#123 --wait

To work on local changes with Fast Refresh or hot reload, continue to Local development.