Local vs Remote mode

Every RubyEverywhere app runs in one of two modes. The mode decides where your Ruby runs, which platforms you can target, and which gems you can use. Set it once in everywhere.yml.

Local mode#

Local mode compiles your whole app, Ruby runtime included, into the binary and ships it to the user. When they open the app, the native shell boots that compiled server on their own machine and points the window at it. Everything runs on the device. Nothing to deploy, no network needed.

Declare it with mode: local:

app:
  name: Notes
  bundle_id: com.example.notes
  mode: local
  entry_path: /notes

Because the app has to run self-contained on someone else's machine, local mode supports a narrower set of gems. SQLite is the only database: there is no Postgres or MySQL server on the user's machine to talk to. Anything that assumes outside infrastructure (a shared database, a job server, another host) does not fit.

Local mode suits:

• Self-contained desktop apps that own their data locally.
• Apps that must work offline, with nothing to deploy.
• Shipping one double-clickable binary that installs nothing.

Local mode is desktop only. iOS and Android cannot run it: a phone cannot boot a compiled Rails server the way a desktop can. For mobile, use remote mode.

Remote mode#

Remote mode ships a thin native shell, around 6 MB, around an app you have already deployed. No Ruby is compiled or bundled. The shell opens a native window pointed at your remote.url. Your app runs on your server exactly as it does in a browser, and the shell adds the native window, menus, tab bar, and the Bridge API.

app:
  name: Afomera Dev
  bundle_id: dev.afomera.desktop
  mode: remote

remote:
  url: https://afomera.dev

Since your app runs on real infrastructure, there are no gem or database limits. Use Postgres, background jobs, anything your deployed stack already runs.

Remote mode suits:

• Teams who deploy their app (Hatchbox, Fly, Render, their own servers) and want a native wrapper around it.
• Apps that need a server database, background jobs, or shared state.
• Mobile. iOS and Android need remote mode, and desktop works too.

Which should I use?#

Rule of thumb: desktop only and self-contained, use local. Already deployed, or you want mobile, use remote. Either way the Bridge API and the rest of everywhere.yml work the same.