solana-mobile

Solana Mobile projects

Set up and maintain Solana Mobile apps. The solana-mobile CLI does the scaffolding, environment checks, and emulator management — prefer it over hand-rolled setup.

Run it without installing:

npx solana-mobile@latest --help

pnpm dlx solana-mobile@latest and bunx solana-mobile@latest are the equivalents. Match whichever package manager the project already uses, and keep @latest so the runner does not reuse an older cached version.

Every flag of every command: references/cli.md. Do not guess at flags — the CLI ships its own help, and --help on any command is authoritative.

Non-negotiable constraint

Mobile Wallet Adapter requires a development build. Expo Go will not work — MWA depends on native Android modules that Expo Go does not bundle. If someone reports wallet connection failing in Expo Go, that is the cause; there is no workaround, they need expo run:android.

Android is the only platform with wallet support. iOS builds run, but no MWA.

First: work out which situation you are in

Create a new project

npx solana-mobile@latest create

Interactive by default. To skip the prompts, name the project and template:

npx solana-mobile@latest create my-app --template expo-kit-wallet

Useful flags:

Choosing a template

Templates come in two families. Pick an expo-kit-* template. @solana/kit is the current Solana client library, and these are the templates the CLI maintains most actively.

Reach for expo-web3js-* only when the user is deliberately continuing an existing @solana/web3.js codebase, or asks for it by name. If they ask without a reason, say kit is the better starting point before going along with it — a new app on web3.js starts life needing a migration.

expo-kit-minimal is the clearest reference for how the kit pieces fit together, and worth reading even when building on a different template.

Template ids are also accepted in full gh:solana-mobile/templates/mobile/<name> form. Re-run --list-templates rather than trusting this table if a template seems missing — the catalog ships with the CLI, not with this skill.

After scaffolding

cd my-app && npm run android

That runs expo run:android, which builds and installs the development build. The first Android build is slow (Gradle cold start); later builds reuse the cache.

Check the environment

Before debugging a build failure, check the toolchain:

npx solana-mobile@latest doctor

It reports on the local Android and Node toolchain with recommendations for anything missing. --json gives a stable report worth parsing when you need to branch on a specific check; --verbose adds resolved paths and diagnostics.

Run doctor first whenever a build fails for reasons that are not obviously in app code.

Manage Android emulators

npx solana-mobile@latest emu list
npx solana-mobile@latest emu status
npx solana-mobile@latest emu create
npx solana-mobile@latest emu start my_phone
npx solana-mobile@latest emu stop my_phone

emu is an alias for emulator. Subcommands: create, delete, images, list, start, status, stop, tune. System images live under emu images (install, list, delete).

Create a named emulator on a specific device profile:

npx solana-mobile@latest emu create local_phone --device pixel_9

Prepare a fresh emulator

A newly created AVD is not ready for wallet work: it is not running, its first-run dialogs are still armed, and it has no wallet app. Boot it tuned, then install one — in that order, since device install needs a booted device to install onto:

npx solana-mobile@latest emu start local_phone --tune
npx solana-mobile@latest device install fakewallet

--tune disables the animations, first-run dialogs, lock screen, and notifications that otherwise sit on top of the app on a fresh AVD. Tuning is opt-in — emu start and emu create --start apply it only when passed --tune — and in that form it is non-interactive, which is what makes it the one to reach for in a script. emu create takes --start --tune to do all of this at creation time.

device install fakewallet puts the Mobile Wallet Adapter test wallet on the running emulator. Without a wallet app, MWA has nothing to hand off to and connect silently does nothing — the most common cause of "connect does nothing on the emulator".

Anything gated on the Seeker Genesis Token still needs a real Seeker device; an emulator cannot hold one. See the seeker-genesis-token skill.

Work with a connected device

device covers everything that goes over adb, for emulators and physical phones alike.

npx solana-mobile@latest device list                       # serials, states, names
npx solana-mobile@latest device install fakewallet         # catalog APK
npx solana-mobile@latest device install ./app-release.apk  # local file
npx solana-mobile@latest device open http://localhost:3000 # opens on the device
npx solana-mobile@latest device tune --all -y              # prepare for automation

device open creates the adb reverse for a localhost URL itself, so a dev server on this machine is reachable from a USB-connected phone. Prefer it to hand-written adb reverse plus am start incantations.

device tune and emu tune apply the same tweaks but differ in two ways, and the second one bites in scripts. device tune accepts physical devices, takes --device <serial> or --all, and falls back to the only connected device. emu tune refuses non-emulator serials, takes the AVD name or serial as a positional argument, and opens a picker whenever it is given none — even with exactly one emulator running, and even under -y, which skips the tweak prompt and not the emulator one. Name the target in anything unattended: emu tune local_phone -y.

Run a local validator

npx solana-mobile@latest localnet start
npx solana-mobile@latest localnet check

localnet start gets a validator serving on the host and forwards its ports to every connected device, so the app reaches localhost:8899 as if the validator ran on the device. It reuses a localnet container it already started, attaches to a validator already answering on those ports — a native one, needing no Docker at all — and starts a container only when neither is there. check verifies reachability from each device — which is the question to ask when an app cannot see a validator that is plainly running on this machine.

localnet forward re-applies the forwards after plugging in a new device, and logs, status, and stop do what they say.

Test a wallet without an app

npx solana-mobile@latest playground

Serves a wallet testing page, opens it on the device, and streams every MWA interaction back to the terminal: connect, sign in (SIWS), sign message, sign transaction, sign and send. It runs against devnet by default; --cluster localnet points it at the localnet validator, and mainnet needs your own --url because the public endpoint rejects browser-origin requests.

Use this to split an app bug from a setup bug. If the playground cannot sign either, the problem is the wallet or the device, not the code being debugged. It needs an MWA wallet installed — device install fakewallet if there is none.

Reference material

• references/cli.md — every solana-mobile command and flag, including templates and webshell
• references/add-to-existing-app.md — wiring Solana into an Expo app that already exists: crypto polyfill, providers, dependencies
• references/troubleshooting.md — build, polyfill, and emulator failures with known causes

Related skills

• solana-mobile-wallet — connecting wallets, signing, sending transactions
• solana-mobile-publishing — signing a release APK and shipping to the dApp Store
• seeker-genesis-token — verifying Seeker device ownership
• seeker-domains — .skr domain name resolution

For general non-mobile Solana work — Anchor or Pinocchio programs, Codama client generation, testing, security review — use the Solana Foundation's solana-dev skill instead. create installs it into .agents/skills/solana-dev/, so a scaffolded project already has it.

Links

• CLI source: https://github.com/solana-mobile/solana-mobile-cli
• Templates: https://github.com/solana-mobile/templates
• Solana Mobile docs: https://docs.solanamobile.com