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

After model setup, follow the Baby game example: create an Expo project, ask for a game, approve the edit, and try Animal Parade in Native Preview.

  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.

    For this demo, enter Baby game, select Expo, leave the optional repository field empty, and tap Create and open Agent.

    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.

    The entire request in this demo is ‘Make a game for baby.’ The Agent plans a game with large touch targets, gentle feedback, and six animal cards.

  4. Review · Allow once · Activity

    Follow the work and review the result

    In Review mode, RunWhale asks before the Agent writes index.tsx. Tap Allow once to approve this edit, then follow the file-write and check activity in the same session.

    The Agent runs TypeScript diagnostics and a Git diff. Its summary reports unresolved dependencies in the fresh workspace, then it moves to Native Preview to check the app by running it.

  5. Run / Reload · Preview

    Run the same project in Preview

    In the recording, the Agent launches Native Preview directly. You can also tap the refresh icon (Run / Reload) after a turn finishes. Web projects use Web Preview; compatible Expo projects use 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. Native Preview · Animal Parade

    Tap the animals and check the response

    Animal Parade opens with ‘Can you find the Dog?’ above six cards: Dog, Cat, Cow, Chick, Frog, and Lion. Tap the cards and watch the prompt and feedback change.

    The demo shows ‘Yay!’, ‘Great job!’, and ‘You found it!’ responses before another animal prompt appears. For your next change, return to the same saved Agent session.

From prompt to play

Create the project, send one prompt, approve the file write, follow the checks, open Native Preview, and try the game.

RunWhale New Project screen with Baby game entered, Expo selected, and the optional Git repository field empty.
Create Baby game with Expo.
RunWhale Agent session showing Make a game for baby and a plan for large touch targets, gentle feedback, and no failure state.
Ask: Make a game for baby.
RunWhale asking permission to write index.tsx, with Reject and Allow once buttons.
Approve the file change.
TypeScript diagnostics and Git diff activity, followed by the Agent's unresolved-dependency summary before Native Preview.
Follow the checks before Preview.
Animal Parade in Native Preview with Can you find the Dog? above six colorful cards: Dog, Cat, Cow, Chick, Frog, and Lion.
Play Animal Parade in Native Preview.
Animal Parade displaying Great job! beside the Lion icon after an interaction in Native Preview.
Tap an animal and see the response.

Full walkthrough

Watch the workflow from prompt to Preview

In about 2 minutes 12 seconds, this silent recording follows Baby game from project creation and one short prompt through file-write approval, checks, and interaction with Animal Parade in Native Preview.

All six screenshots are frames from the demo above, with the original English interface. RunWhale Community Edition is free and open source. AI provider usage charges may apply.

Animal Parade · Full demo · About 2 min 12 sec · No audio

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.