RunWhale
中文Back to home

Guide

Get started with RunWhale

Configure your model, open a real project, ask the Agent to make a change, and test the result on your phone.

Last updated:

Before your first prompt

RunWhale keeps the development workspace on your phone, while model inference uses the provider you configure. These three checks make the first run smoother.

Bring a model API key

Use a key from your chosen model provider. Save it only through RunWhale Settings—never in a project or prompt.

Stay online for Agent work

Model inference needs the network. Git network operations and uncached dependency downloads may need it too.

Start with a compatible project

Choose a built-in Web or Expo starter, or import a compatible repository with a valid RunWhale Preview entry.

Core workflow

From setup to a tested result

The example below follows the same Snake Sprint project from creation through a working Native Preview and a tested follow-up change.

  1. Settings → Models · Save securely

    Configure a provider and model

    Open Settings → Models, choose the provider and model you want to use, paste that provider's API key, and tap Save securely.

    The key stays in the device's secure storage. Agent inference uses the selected provider, so the device must be online when you send a prompt.

  2. New project · Web / Expo

    Create a project or import a repository

    Tap New project, give it a name, and choose Web for a React website with Web Preview or Expo for an app with Native Preview.

    To continue an existing codebase, enter a compatible Git repository instead. The imported project's runwhale.json determines its Preview target.

  3. Agent

    Describe one clear result

    Tell the Agent what you want to build or change. Include the intended behavior and ask it to run the supported checks that matter to the task.

    For Snake Sprint, the first request turns the Expo starter into a portrait game with movement, scoring, controls, and collision behavior.

  4. Activity · Files

    Follow the work and review the result

    Watch the Agent activity, inspect the files it changed, and read the result of its checks. In Review permission mode, approve or reject write-capable actions when RunWhale asks.

    If a dependency request appears, check the package and plan before allowing it once. RunWhale supports compatible pure-JavaScript packages from the npm registry; native addons, binaries, install scripts, and project-specific native SDKs stay outside the current runtime.

  5. Run / Reload · Preview

    Run the same project in Preview

    Tap the refresh icon (labeled Run / Reload) after the turn finishes. A Web project opens Web Preview; a compatible Expo project opens Native Preview.

    Interact with the result instead of checking only the first screen. If Preview reports a diagnostic, return to the project and use that exact message for the next fix.

  6. Follow-up · Run / Reload

    Refine and test a real state

    Continue in the same saved session with a focused follow-up. In the example, the Agent adds Obstacle Mode without starting over.

    Reload Preview, exercise the new behavior, and verify a meaningful state. Snake Sprint is tested by enabling the mode and reaching a genuine Game Over state.

From prompt to play

Start with an Expo project, turn a prompt into Snake Sprint, preview it, add Obstacle Mode, and verify a real interaction state.

RunWhale New Project screen with the public demo name Snake Sprint, Expo selected, the optional Git field empty, and Create and open Agent ready.
Start with Web or Expo.
RunWhale Agent session reasoning through real Snake movement and collision logic while the session is running.
Turn intent into code with an Agent.
Full-screen Snake Sprint Native Preview with the game running and the left direction control visibly pressed.
Run it in Native Preview.
The same RunWhale Agent session planning three orange obstacle clusters, an Obstacle Mode toggle, and restart behavior for the follow-up turn.
Refine with a follow-up request.
Snake Sprint Native Preview in Ready state with Obstacle Mode enabled and three orange obstacle clusters visible on the board.
See new features come to life.
Snake Sprint Native Preview showing Obstacle Mode enabled and a genuine Game Over state after the snake reaches the lower orange barrier.
Test real interaction states.

Full walkthrough

Watch the workflow from prompt to Preview

This silent recording follows the same project through creation, Agent work, Native Preview, a follow-up request, and final interaction testing.

The product UI was captured in English from an iOS Simulator development build. The surrounding artwork is presentation framing; the workflow is real, and these images do not imply App Store availability.

Silent workflow recording · iOS Simulator development build

Keep learning

Read common answersUnderstand connectivity, data handling, project limits, Git, and common failures.Contact supportSend a private request or report a reproducible, non-sensitive issue on GitHub.Review data handlingSee what stays on your device and what is sent to services you choose.Explore the sourceRead the public RunWhale repository, project scope, and contribution guidance.