Open source, MIT v0.3 Beta Flutter host + any static web build Android today · iOS experimental

Keep the core. Swap the shell.

Your web app becomes your mobile app’s interface. A small Flutter host ships through the stores once. Every UI release after that is signed, tried on each phone and rolled back on its own if it fails to start. Data lives in native SQLite, so the app works offline from the first launch.

$npm create valence@latest
Read the docs
Try the release flow

A reference app running on a simulated phone. The console follows the update rules in the spec, with time sped up: release a bundle, restart the phone, ship a broken build and watch it revert.

Reference app · app.valence.reference channels/production.json → seq 42
10:24

On your laptop
On a user’s phone
The sync button inside the app calls sync.now over the bridge.

Next

valence/state.json

                  
log
    Inside the app

    A small native host. Everything users see is your web build.

    The Flutter host goes through store review and rarely changes. It serves your web build from the phone itself, keeps data in SQLite, and checks for new signed bundles in the background.

    How the Flutter host works

    The Valence hermit crab stepping out of an old phone-shaped shell into a new one
    The host stays. The shell gets swapped.
    Flutter host store-reviewed, rarely changes
    WebViewYour web build, served by the app’s own server on 127.0.0.1
    Typed bridge per-launch nonce · strict decoding
    SQLitekv, bucket, outbox and prefs, starting from seed.db
    Updaterpointer → signed manifest → changed files
    Your sync APIor static chunks on a CDN
    Static OTA hostR2, S3 or any CDN
    Only new native features wait for a store release.
    What changedHow it reaches usersStore review
    UI, copy, styles, web logicA signed over-the-air bundle with a staged rollout: 10%, then 50%, then 100%Not needed
    Data, or a fix to bundled dataSync. The fix is a new row with a higher sequence number.Not needed
    A new native capability or feature areaA normal app releaseRequired
    Release path

    Signed on your laptop, verified on every phone.

    A release is a set of content-addressed files, a manifest signed with Ed25519, and a small pointer that says which manifest is live. Phones download only the files whose hash changed.

    Read the release guide

    The Valence hermit crab holding an envelope closed with a wax seal
    Every bundle arrives signed.
    1. 01

      Build and sign

      valence bundle hashes every file, writes the manifest with the page’s CSP, and signs it. It refuses any native code.

    2. 02

      Upload, pointer last

      Files go up first, then the manifest and its .sig, then the pointer. A phone never sees a manifest whose files are missing.

    3. 03

      Verify in a fixed order

      Signature, then appId, then seq against the pointer, then the floor, then requires, then every path, hash and size. Any failure stops the update.

    4. 04

      Try it on the next launch

      The new bundle runs as a trial. Your web app calls ready() once it has painted — on every path, including a first-run screen — and that call commits the update.

    5. 05

      Commit, or go back

      No ready() within 15 seconds of foreground time means the phone returns to the last good version. A second failure marks the bundle bad. The bundle built into the app is the final fallback.

    manifests/43.jsonsigned · keyId k1
    {
      "format": 1,
      "appId": "app.valence.reference",
      "seq": 43,
      "version": "2026.10.16+43",
      "floor": 40,
      "requires": { "bridge": 1, "data": { "schedule": 2 } },
      "entry": "index.html",
      "csp": "default-src 'self'; script-src 'self' 'sha256-…'; frame-src 'none'",
      "urgent": false,
      "routes": ["/", "/schedule", "/settings"],
      "files": {
        "index.html": { "h": "9f2c41…e41a", "n": 1834 },
        "_app/immutable/entry/start.js": { "h": "03bd7e…a9c0", "n": 48210 }
      },
      "keyId": "k1"
    }
    seq only goes up. It is the bundle’s identity; version is for display.
    floor is the lowest seq a phone may run after this one. Raise it after a security fix.
    csp is computed at build time and sent as the entry page’s header.
    routes are compared with the last store-reviewed build to catch purpose drift.
    The Valence hermit crab tucked back inside its old shell

    Rolling back means rolling forward. Release the last good commit again. It gets a new, higher seq, so every phone moves forward to it. Phones still trying the bad bundle revert on their own.

    Using an existing REST API? Keep selected responses offline with a store-enabled cache. Synced data and user edits retain their own histories.

    Offline first

    The first launch works with no network at all.

    The app ships with seed.db, so every screen has data before the phone has ever been online. After that, the phone asks for everything after the last row it has.

    Read about complete pulls and ordered offline writes

    usn 1 – 1240 · shipped in the app
    1241 – 1242 · sync
    GET /schedule?since=1240&schema=2&limit=500 → 200 · 2 rows · max 1242 · more: false
    1. usn 1239schedule/day-2Day 2 sessionsseed
    2. usn 1240schedule/day-1Day 1, offline talk in Hall Bseed
    3. usn 1241schedule/day-2Day 2, adds a workshop at 14:00new
    4. usn 1242schedule/day-1Day 1, offline talk moved to Hall C, lightning talks at 16:30fix
    sqlite · the whole data layer
    CREATE TABLE kv     (bucket, schema, key, value, usn, deleted)  -- JSON values
    CREATE TABLE bucket (name, schema, max_usn, synced_at)       -- where each pull resumes
    CREATE TABLE outbox (id, bucket, key, value, deleted, created_at)
    CREATE TABLE prefs  (key, value)
    PRAGMA journal_mode = WAL;
    • Pull by sequence number. Rows arrive in order and each page is applied in one transaction, so a dropped connection never leaves half a page.
    • Corrections are just newer rows. A wrong room in the seed is fixed by a row with a higher usn. There is no separate patch system.
    • Local writes win until acknowledged. data.put writes the row and an outbox entry together. Push is idempotent by op id, and the server keeps the last write per key.
    • The UI and its data move together. Read-only data is stored per schema version, so a trial that reverts still has the data its old UI expects.
    • No backend needed for public data. Publish static chunks on a CDN and phones fetch only the chunks above what they already have.
    Typed bridge

    One schema, so Dart and TypeScript can’t drift apart.

    You describe the bridge once in bridge.schema.json. Codegen writes the Dart handler interface for the host and the TypeScript types for your web app. CI runs codegen --check and fails when they are stale.

    Read the bridge guide

    {
      "version": 1,
      "methods": {
        "app.ready": { "since": 1, "params": {}, "returns": "void" },
        "data.get":  { "since": 1, "params": { "bucket": "string", "key": "string" }, "returns": "json?" },
        "data.list": { "since": 1, "params": { "bucket": "string", "prefix": "string?", "limit": "int?" }, "returns": "Row[]" },
        "data.put":  { "since": 1, "params": { "bucket": "string", "key": "string", "value": "json?" }, "returns": "void" },
        "sync.now":  { "since": 1, "params": { "buckets": "string[]?" }, "returns": "SyncResult" }
      },
      "events": {
        "sync.changed":       { "since": 1, "payload": { "buckets": "string[]" } },
        "bundle.updateReady": { "since": 1, "payload": { "seq": "int" } }
      },
      "types": {
        "Row":        { "key": "string", "value": "json", "usn": "int" },
        "SyncResult": { "buckets": "string[]", "changed": "int", "offline": "bool", "reason": "string?" }
      }
    }

    Only your own pages can call it

    The app’s loopback server writes a per-launch nonce into the entry page. Messages without it are refused, so a page served by anything else gets no bridge.

    Strict decoding on the host

    Unknown fields, wrong types and non-JSON input are rejected before a handler runs. Replies are built with jsonEncode, never by joining strings into a script.

    A locked frame

    The WebView stays on 127.0.0.1, other URLs open in the browser, and there are no off-origin subframes. The page’s CSP comes from the signed manifest.

    Store policy

    Allowed by both stores, within limits.

    Downloading JavaScript into a WebView is permitted on iOS and Android if it keeps the app’s purpose. Apple also bars downloaded code that adds features (Guideline 2.5.2), so new features ship with a store build. Valence checks the parts a machine can check. App review has the final say.

    Apple Developer Program License Agreement §3.3.1(B)
    “Interpreted code may be downloaded to an Application but only so long as such code: (a) does not change the primary purpose of the Application … (b) does not bypass signing, sandbox, or other security features of the OS; and (c) … does not create a store or storefront for other Applications.”
    Google Play, Device and Network Abuse policy
    “An app distributed via Google Play may not modify, replace, or update itself using any method other than Google Play’s update mechanism. … This restriction does not apply to code that runs in a virtual machine or an interpreter where either provides indirect access to Android APIs (such as JavaScript in a webview or browser).”

    Native code can never be downloaded

    The bundler rejects these anywhere in a path:

    .so.dex.jar.apk.aab.ipa.dylib.framework.a.o.class.exe.dll

    Purpose drift is flagged

    Each release’s top-level routes are compared with the bundle you last submitted to the store. A new route raises a warning, because a new feature area should go out with a store update.

    Real native value

    To avoid the “repackaged website” rejection, the host ships at least two of: offline cold start, notifications, a home-screen widget, share and haptics, biometric lock.

    First launch never waits

    The built-in bundle and the seed make the app fully usable offline, so a first launch never blocks on a download.

    No untrusted pages

    Play flags a JavaScript interface that loads untrusted content. The bridge only answers pages from the app’s own local server.

    A CDN can’t push code

    Every manifest is signed and every file is checked against its hash. Someone who controls the CDN can freeze phones on their current bundle, but can’t serve new code.

    Policy text retrieved 2026-10-14 and 2026-10-16. Not legal advice. The exact quotes and the rules built on them are in the store policy guide.

    Get started

    One command from your project root.

    The wizard does everything that doesn’t need AI in a few seconds. It is safe to run again: it never overwrites your config, your schema or files you’ve edited.

    Follow the quick start

    ~/my-app
    $ npm create valence@latest
    # then, in Claude Code
    $ claude "/valence init"
    
    # later
    $ npx create-valence@latest update    # CLI, skill and agents
    $ npx create-valence doctor --tests   # mechanical checks
    
    # no Claude Code? the CLI is vendored into your repo
    $ node valence/valence.mjs bundle
    $ node valence/valence.mjs codegen --check
    1. 01Detects your web app (SvelteKit, Next.js static export, Astro or Vite), its package manager, an existing Flutter project and your app id.
    2. 02Writes valence.config.json and the bridge schema, and declares @getvalence/bridge in your web app.
    3. 03Generates your Ed25519 signing key outside the repo, and the typed bridge code.
    4. 04Installs the /valence skill and its agents into .claude/.
    5. 05Offers to launch /valence init, which adds the valence package, writes the host setup, wires your web app, runs the tests and has a separate reviewer agent check the result.
    /valence initAdd the host package, keys, bridge, offline store and tests.
    /valence releaseBuild, sign and stage a bundle. Uploads only after you confirm.
    /valence doctorCheck versions, store policy, signatures and tests.
    Questions

    Before you ship it.

    How does my app ask for OS permissions?
    Schema 10 adds checks, foreground requests, app settings and resume changes for seven permission kinds. The store build compiles its allowlist and native declarations; an OTA cannot expand it. See Permissions for status handling and setup. iOS is experimental and untested.
    How do I show unsynced edits or read several records?
    Schema 3 adds sync.status for the outbox count, including deletes, and data.getMany for up to 500 keys in one call. The status reads local observations without starting a sync. See offline tooling for older-host guards, seed schemas, channels and mechanical diagnostics.
    How does my page know it was backgrounded, or that an update is waiting?
    Schema 6 adds three events and two methods. app.lifecycle gives you four states rather than Flutter’s five — foreground, background, inactive, detached — so you can save a draft when the user swipes away, which a page could not hear about before. app.online reports what the OS says about network interfaces, which is not reachability: use it to decide whether to try, and SyncResult.reason to say whether the last attempt worked. sync.done fires after every sync the host runs on its own, including the ones that moved nothing, so a “last synced” line stays true. bundle.status says why an update declined — one of eleven named reasons, so “rolled out to 10% of installs”, “still pulling the data this release needs” and “this release is signed with the wrong key” stop being the same silence. And bundle.updateReady pushes you the seq the moment a bundle is ready, so “an update is waiting” appears without polling for it. Foreground connectivity reports also retry the signed update check, including Wi-Fi/cellular handovers; an offline result describes the last attempt until another check completes. Update checks after reconnect. Lifecycle, connectivity and updates.
    Will Apple or Google reject an app built this way?
    Both stores allow JavaScript running in a WebView to be downloaded, as long as it doesn’t change the app’s advertised purpose, bypass OS security or create a storefront, and Apple expects new features to go through review. Valence guards against the common rejections: the host must add real native value, new top-level routes are flagged for a store release and the bridge is locked to the app’s own pages. Reviewers judge each app, so no tool can promise approval.
    What happens to users when a release is broken?
    Each phone tries a new bundle as a trial on the next launch. If the page doesn’t call ready() within 15 seconds of foreground time, or the app dies first, the phone goes back to the last good version. After a second failure the bundle is marked bad on that phone. Start with a 10% rollout and most users never see it.
    What happens if the phone runs out of memory?
    Your page runs in a separate process from the app, the way a browser gives each tab its own — and on Android, when memory runs short, the system kills that one first. No released webview_flutter_android lets an app say “I handled it”, so the app is closed too and the user reopens it. Valence 0.4 cannot prevent that on Android and says so plainly, including how to recognise it in a log; a fix needs native code and is planned for 0.5. Your data is safe either way, because it lives in SQLite. One thing to plan for: because no app code runs, the next launch cannot tell this apart from a crash in the release itself, so an eviction while a new release is on trial costs it one of its two strikes — start rollouts at 10%.
    Can a compromised CDN push code to my users?
    No, as long as your signing key stays private. Every manifest is signed, and every file is checked against its hash and size. The pointer is unsigned so you can change the rollout without re-signing; someone who controls it can freeze phones on their current bundle or change who is in the rollout, and nothing more.
    Does my place survive Android reclaiming the app?
    Valence restores the route and a small UI draft when you return to a retained task. Explicit task closure starts fresh. State restoration explains the limits; iOS remains experimental and untested.
    Can a link open a screen in my app?
    Android App Links and custom schemes can open a local route in your signed UI. The store build fixes which origins are accepted; your web router handles the path. Set up deep links, including website association files. iOS support is experimental and untested.
    Can I use hot reload inside the app?
    Use valence dev with a debug Flutter build. Vite HMR or Fast Refresh updates the page while the native bridge remains available. Release and profile builds exclude the dev proxy. Use test accounts and a separate development app id. Live development guide.
    Can I use my existing REST API?
    Use http.request for online actions: the native host calls your API without WebView CORS restrictions, attaches your user token, and enforces the API origins compiled into the app. For larger JSON responses, grant a bounded response size in a store build; the bridge reply limit still applies. A failure says which kind it was: no network, a timeout, or something it cannot tell apart. A store build can opt one origin into a host-held cookie jar for cookie-paired CSRF; bounded persistent sessions need a separate compiled grant. For selected offline responses, enable revision-18 REST caching in the store build. Server-managed datasets and queued user writes use the sync protocol. The backend guide includes a reference Node adapter.
    Can my app have user accounts?
    Yes, and you keep your own login. Your web app authenticates against your API however it already does, then hands the host the token with auth.setToken. The host keeps it in the Android Keystore — never in the database — and sends Authorization: Bearer on every sync of the user’s own data, including the background runs your JavaScript is not awake for. The page can replace or clear the token but never read it back, and a 401 raises auth.expired so you can refresh or show a login screen. Valence is not an identity provider: sessions, refresh and password resets stay your API’s job.
    Can my backend send push notifications?
    Opt-in Firebase messaging adds typed notification events, taps, and data-only sync hints. Android background notifications support images. This new capability still needs a maintainer Firebase project for device validation; iOS/APNs is experimental and untested. Configure remote push in a store build.
    Does it work on iOS?
    Not yet, honestly. Android is the tested platform: everything in the spec has been built and run on Android phones and emulators. The iOS paths are specified and implemented — App Groups for the widget, the backup exclusion, rebinding the loopback port on resume, background sync through BGTaskScheduler — but nobody has run them, because there is no Apple hardware on the machines Valence is developed on. Treat iOS as experimental and untested, and expect to do the first run yourself.
    Can I fix a bug in the host without touching every app?
    Yes — that is why the runtime is a package. Before 0.4 the host was generated into each app, so one bug in the rollback loop meant four hand-applied fixes in four apps. Now the OTA verification, the rollback state machine, the SQLite store and the bridge trust boundary live in valence and @getvalence/bridge, and a fix reaches an app with flutter pub upgrade or npm update. The rule that makes it work: never vendor or patch either package.
    Which web frameworks work?
    Any SPA that builds to static files. The wizard detects SvelteKit, Next.js static export, Astro and Vite. When window.Valence is absent, bridge calls go to a web shim, so the same build is also your website.
    Do I need Claude Code?
    No. The host runtime is the valence package and the web client is @getvalence/bridge, so there is no large implementation job either way — flutter pub add valence, then about twenty lines of main.dart. The CLI is zero-dependency Node and the wizard vendors it into your repo, so CI needs no install. Claude Code adds the /valence workflows that wire it up, run the tests and review the result.
    Does the interface follow phone accessibility settings?
    The host supplies safe-area CSS variables, Android system text zoom and dark-mode, high-contrast and reduced-motion signals. Your page still needs semantic HTML, readable contrast and usable touch targets. The accessibility guide explains the setup and device checks. iOS is experimental and untested.
    Can the web UI schedule local reminders?
    Yes. Schema 11 includes native reminders with honest exact/inexact timing, images, action buttons and cold-start taps, and schema 16 adds notify.pendingIds() so a full queue can still be read back for a refill. Enable the group in a store build and install the native setup. Local reminder setup. iOS remains experimental and untested.
    Can I add my own native features?
    Package them as a Valence plugin: a Dart handler, a namespaced schema fragment, matching npm types and native setup notes. Codegen merges it into your typed bridge. Native additions ship through a store release; plugins cannot be downloaded over the air.
    Can users share a chart or card?
    Use schema-14 share.image to open the native share sheet with a PNG or JPEG and a caption. It accepts small inline bytes or an image from the active signed bundle. The result describes selection, not delivery. Image sharing and limits. iOS is experimental and untested.
    Can I require users to install a newer store build?
    A supporting host can enforce a signed minimum-host policy with a native update screen while retaining saved data. Older runtimes and phones that have never received the policy cannot be forced. See Forcing an update for the release order and signed withdrawal.
    What is out of scope?
    Third-party mini-app stores (Apple guideline 4.7), CRDTs and real-time collaboration, and downloading native code.
    How mature is it?
    It is in beta: the spec and commands may still change before 1.0. The runtime is two published packages — valence on pub.dev for the Flutter host and @getvalence/bridge on npm for the web client — each with its own test suite, and the host package runs the spec’s whole acceptance matrix. The CLI, the spec and codegen are tested too. What is missing is production mileage: no app is live on Valence yet. Apps with a 0.3 generated host follow one documented migration.
    Can you set Valence up for us?
    Yes. If you want Valence in your app without learning it first — the Flutter host, signing, the release pipeline and your first over-the-air update — write to [email protected].
    How do pages handle different host versions?
    Typed method gates and the built-in capability revision let pages keep older-host fallbacks. Capability and status fields also retain sync outcomes and expose signed update urgency.

    Your website is already your app.

    $npm create valence@latest
    View on GitHub
    The Valence hermit crab waving