Build, test and run Flutter apps on a remote machine instead of your own CPU. A small laptop that freezes on flutter build apk stays cool: the Gradle and Dart work happens on an instabox box, a Daytona sandbox or any Linux server you can ssh into, and the finished .apk, .aab or web build is copied back into ./build. rflutter run even hot-reloads on the phone plugged into your computer through a tunnel.
It is the Flutter sibling of rcargo and works the same way: your working tree (uncommitted and private code included, plus path: dependencies) is delta-synced over plain ssh + tar. No GitHub access, no rsync.
rflutter build apk --release # builds remotely, ./build/app/outputs/flutter-apk/app-release.apk appears locally
rflutter --install build apk --release # ...and installs it on the phone plugged into this computer
rflutter build appbundle --release --flavor prod
rflutter build web # ./build/web
rflutter test
rflutter analyze
rflutter run # app on your phone, built remotely, hot reload on save
rflutter run -d web-server # app in your browser at http://localhost:PORT
rflutter install android # extra tools on the build machine (see below)
Anything that is not an rflutter command is passed to flutter and run remotely; rflutter dart ... runs the Dart CLI (rflutter dart run build_runner build).
Open your Flutter project in Claude Code, Codex, Cursor or any agent that can run shell commands, and paste the prompt below. The agent installs rflutter, wires itself up, walks you through anything it cannot do for you (logins, keys), and then proves it works.
Set up rflutter in this project so that Flutter builds and tests run on a remote machine instead of on this computer. rflutter is https://github.com/igun997/rflutter (read its README if you need details).
Work through these steps in order. Whenever a step needs me (a browser login, an API key, choosing a provider, installing software), stop, tell me in plain words exactly what to do and which command or link to use, and wait for me to say it is done. Never invent or guess credentials, and never ask me to paste secrets into this chat.
1. Check `rflutter --version`. If it is missing, install the prebuilt binary (nothing to compile):
curl -fsSL https://raw.githubusercontent.com/igun997/rflutter/main/install.sh | sh
If that fails, fall back to: CARGO_BUILD_JOBS=2 cargo install --git https://github.com/igun997/rflutter
Make sure the install folder (usually ~/.local/bin) is on PATH for this session.
2. Go to the folder that contains this project's pubspec.yaml and run `rflutter init`. It creates rflutter.toml, installs the agent skill, registers the MCP server, and installs a guard that blocks local flutter builds.
3. Run `rflutter onboard --live`. If it prints SETUP REQUIRED, follow its steps: run the steps that are not marked [USER] yourself, and for [USER] steps ask me. If no remote machine is configured, ask me which I want and recommend instabox (easiest, has a free tier):
- instabox: `npx instabox@latest` (signs in and installs its CLI), then `rflutter instances add main --backend instabox --default --description "general purpose Flutter builder"`. If I prefer an API key (no CLI needed), I create one in the instabox dashboard and set INSTABOX_API_KEY.
- Daytona: I run `daytona login` (or set DAYTONA_API_KEY), then `rflutter instances add dt --backend daytona --set cpu=4 --set memory=8 --set disk=20 --default --description "Daytona sandbox, 4 vCPU"` (Daytona's default sandbox is far too small for Android builds; lower the numbers only if my plan's quota is smaller, never disk below 12)
- my own server: `rflutter instances add vps --backend ssh --set host=USER@SERVER --default --description "my build server"` (key-based ssh must already work; Debian or Ubuntu with sudo or root)
If I already have several machines, run `rflutter instances discover`, and register each one with a description that says what it is good for (for example "32 cores, use for release builds").
4. Run `rflutter remote doctor`, then `rflutter build apk --debug` (or `rflutter test` if the project has tests) and show me the result. The first build on a new machine installs Flutter and the Android SDK there, which takes several minutes and about 8 GB of disk.
5. From now on never run flutter build, test, analyze, run or drive, dart analyze, test, run or compile, or ./gradlew on this computer. Use `rflutter <the same arguments>` instead, or the `flutter` tool of the rflutter MCP server. `rflutter run` (hot reload on my phone) needs my terminal and my phone, so tell me to run it myself. Read .claude/skills/rflutter/SKILL.md (or .agents/skills/rflutter/SKILL.md) now and follow it, including how to choose between instances.
6. Tell me in plain English what you set up, which instance is the default, that I may need to restart this agent so it loads the new MCP server and skill, how to put a build on my phone (`rflutter --install build apk --release`) or hot reload on it (`rflutter run`), and that `rflutter remote down` pauses the remote machine to save money (it wakes up by itself on the next build).
Already set up and just want to add another machine later? Paste this instead:
Add another remote build machine to rflutter. Run `rflutter instances` to see what exists, ask me which provider I want (instabox, Daytona, or my own SSH server), do the steps that do not need me, and ask me for the ones that do (logins, keys). Register it with `rflutter instances add NAME --backend ... --description "what this machine is good for"`, then verify with `rflutter -i NAME remote doctor` and tell me how to use it (`rflutter -i NAME build appbundle --release`).
curl -fsSL https://raw.githubusercontent.com/igun997/rflutter/main/install.sh | sh
# or, from source (build it on a remote machine if your laptop is small):
CARGO_BUILD_JOBS=2 cargo install --git https://github.com/igun997/rfluttercd my_flutter_app
rflutter init # rflutter.toml, agent skill, MCP server, guard against local builds
rflutter onboard --live # tells you exactly what is still missingNo remote machine yet? The simplest is instabox (free tier):
npx instabox@latest # signs in and installs its CLI
rflutter instances add main --backend instabox --default --description "general purpose Flutter builder"| Backend | Register with |
|---|---|
| instabox | rflutter instances add main --backend instabox --default (INSTABOX_API_KEY works instead of the CLI) |
| Daytona | daytona login, then rflutter instances add dt --backend daytona --set cpu=4 --set memory=8 --set disk=20 --default (the default sandbox is far too small for Android) |
| your own server | rflutter instances add vps --backend ssh --set host=USER@SERVER --default (key-based ssh, Debian/Ubuntu, sudo or root) |
Several machines? rflutter instances discover, give each a --description ("32 cores, release builds") and pick with -i NAME.
The first build on a fresh machine installs Flutter (and the Android SDK plus JDK 17 when you build for Android) under ~/.rflutter there, a few minutes, once. Plan for about 3 GB of disk for Flutter and 6 GB more for Android builds.
rflutter remote down pauses the machine to save money; it wakes up by itself on the next command.
rflutter devices # phones attached to this computer (adb)
rflutter run # or: rflutter run -d SERIAL --flavor dev --dart-define=API=stagingHow it works: the remote machine compiles, but the app runs on your phone. rflutter opens a tunnel between this computer and the remote machine: your local adb server is exposed to the remote flutter tool (so install, forward, logcat act on your phone) and the app's Dart VM service is carried back for hot reload. The tunnel rides inside one ordinary ssh session (a small python3 relay on the remote end, installed if missing), so it works even where ssh port forwarding is disabled, as on instabox. Keys work as in flutter run: r hot reload, R hot restart, q quit. Saving a file syncs it and triggers a hot reload automatically (--no-watch or [device] watch = false turns that off). Native or pubspec changes need a rebuild: rflutter tells you.
-d web-server serves the app on the remote machine and the tunnel opens it at http://localhost:PORT on this computer.
Needs adb on your computer (platform-tools) and USB debugging on the phone; rflutter explains each missing piece. The remote and local adb must be the same version: rflutter checks. The tunnel binds loopback on the remote machine, so on a shared server anyone with a shell there could reach your phone's adb for the length of the session: use a machine only you control. iOS devices are not supported (they need a Mac).
What to expect: the first rflutter run uploads the debug apk (about 150 MB for a fresh app) from the build machine to your phone through your own internet uplink; on a 2 MB/s uplink that is over a minute. Hot reloads afterwards send only changed files. Compile errors show up in the terminal exactly as in flutter run, the app keeps running, and the next save reloads again. To get an app onto the phone fast (the apk is downloaded, then installed over USB):
rflutter --install build apk --release # or --debug; --install=SERIAL when several phones are attached
rflutter --install build apk --release --split-per-abi # installs the apk matching the phone's CPUOnly one rflutter run per project at a time. If a tunnel port is taken, rflutter says so; RFLUTTER_PORT_BASE moves it.
.env, *.pem, *.key and signing material (android/key.properties, *.jks, *.keystore, *.p12) are never uploaded by default. For a signed release build, opt in explicitly in rflutter.toml:
[sync]
include = ["android/key.properties", "android/app/upload-keystore.jks"]
[remote]
forward_env = ["KEYSTORE_PASSWORD"] # copied from your shell at run time, never written to diskThose files are then copied to the build machine. rflutter remote doctor warns when key.properties exists but is not listed. Everything else follows .gitignore; build/, .dart_tool/ and .gradle/ never travel.
rflutter install list
rflutter install android # Android SDK + licenses (builds do this on demand)
rflutter install android-pkg "ndk;27.0.12077973"
rflutter install flutter 3.35.1 # another Flutter, side by side; or `stable` to update
rflutter install linux # clang, cmake, ninja, GTK for Linux desktop builds
rflutter install chrome # flutter test --platform chrome
rflutter install bundletool firebase fastlane # one at a time: rflutter install firebase
rflutter install pub melos # dart pub global activate
rflutter install npm firebase-tools
rflutter install apt libsqlite3-devLatest stable by default, or the version in your .fvmrc. Override with [remote] flutter_version = "3.35.1". Several versions coexist on the machine. Only stable releases are installed.
build ios|ipa|macos need macOS and Xcode. On a Linux instance rflutter stops with instructions. Register a Mac as an ssh instance (rflutter instances add mac --backend ssh --set host=me@my-mac), install Flutter there and link it: ln -sfn /path/to/flutter ~/.rflutter/sdk/flutter-stable. rflutter never installs software on a Mac.
rflutter init installs a skill (.claude/skills/rflutter, .agents/skills/rflutter), registers an MCP server (rflutter mcp: tools flutter, install, shell, sync, instances, setup, power, workspaces) and a Claude Code hook that blocks local flutter build/test/run/analyze, dart analyze/test/run/compile and ./gradlew assemble... and points at the rflutter equivalent. Compile errors, Gradle failures, analyzer findings and failing tests come first; progress noise is dropped. Agents cannot run rflutter run (it needs your terminal and phone) and say so.
The copyable setup prompts are at the top of this page.
rflutter.toml in the project (and ~/.config/rflutter/config.toml per user; the project file wins):
instance = "main" # pin this project to one instance
[sync]
exclude = ["data/huge"] # never upload (gitignore syntax)
include = [] # upload even though ignored (signing files)
path_deps = true # follow `path:` dependencies outside the project
[remote]
flutter_version = "3.35.1"
android_packages = ["ndk;27.0.12077973"]
forward_env = ["KEYSTORE_PASSWORD"]
[remote.env]
FLUTTER_STORAGE_BASE_URL = "https://storage.flutter-io.cn"
[device]
watch = true
adb = "/path/to/platform-tools/adb"Environment: RFLUTTER_INSTANCE, RFLUTTER_CONFIG, RFLUTTER_SSH, RFLUTTER_PORT_BASE (first port of the tunnel range, default derived from the project).
rflutter <flutter args> |
run flutter remotely; build pulls outputs (--no-pull to skip) |
rflutter run [flutter run args] |
phone or browser with hot reload |
rflutter devices |
phones attached to this computer |
rflutter install NAME [ARGS] |
utilities on the remote |
rflutter instances [add|rm|use|discover] |
machines |
rflutter remote up|down|status|doctor|setup|sync|shell|ls|gc|rm|destroy |
the remote side |
rflutter init, integrate, onboard, mcp |
setup and agent integration |
Exit codes: flutter's own; 2 rflutter error; 3 setup required (steps printed).
- Remote machines: Debian/Ubuntu Linux for automatic installs; a Mac only by linking an existing Flutter.
flutter runon iOS devices, Windows and desktop windows is not possible remotely.- Remote paths are mapped back to local ones in output, but IDE debugger attach to the VM service is not wired up.
MIT licensed.