The Seed mobile app
The Seed mobile app is the Expo and React Native app for iOS, Android and the web that reads documents and discussions from a Seed site, keeps identities in a vault on the device, and chats with Seed Agents.

The Seed mobile app puts Hypermedia on a phone. People use it to read, to comment and to talk to their agents when they are away from the desktop app. It builds for iOS, Android and the web from one codebase.

The app does five things:

    It opens documents from a Seed site.

    It shows their discussions.

    It lets you comment as one of your identities.

    It shows your notifications.

    It lets you chat with your agents.

The app runs no daemon and keeps no copy of the network. Every read and write goes through a site's Seed API.

Where the code is

The code is in frontend/apps/mobile, package @shm/mobile. It is built with Expo, React Native with the new architecture, React 19, React Navigation and React Query. It stores data with MMKV on a phone and with localStorage on the web.

Path

What it holds

index.ts, App.tsx

The entry point and providers.

src/navigation/RootNavigator.tsx

The screen stack.

src/screens/

Server select, account, identities, vault, vault connect, document, comment, notifications.

src/components/

The React Native views for blocks, embeds, query blocks and discussions, and the comment composer.

src/client/

The Seed API client for the chosen server and its /hm/api/config.

src/vault/

The vault on the device: the encrypted envelope, secure key storage, vault connect and remote sync.

src/agents/

The agents screens.

src/notifications/notify.ts

The signed client for the notify service.

dev/mock-agents-server.ts

A fake app environment with scripted answers, for UI work.

Why it sits outside the pnpm workspace

The root pnpm workspace uses React 18 for the desktop app, and this app's React Native version needs React 19. So pnpm-workspace.yaml leaves this app out, and the app installs its own dependencies with npm. It still uses code from the repository without publishing it:

    @seed-hypermedia/client, the SDK, is aliased to frontend/packages/client in metro.config.js, tsconfig.json and jest.config.js. The client's own dependencies resolve from the root node_modules, so run pnpm install at the root first.

    @shm/ui/agents/* points at the shared agents code. Only .ts files are allowed, so an import of a web component by mistake fails when the app is bundled.

    Metro's resolveRequest forces one copy of react and @tanstack/react-query. Without it, a shared module loads React 18 from the root and its hooks break.

    Metro watches only a short list of package folders. If it watched the repository root, it would read over a million files and watchman would crash again and again. So when you import from a new package, add its folder to that list.

How it talks to the daemon

It runs no daemon. The app talks to one Seed site at a time. You choose the site on the server screen, and the app saves the choice on the device.

    Reads use createSeedClient(serverUrl) from the SDK: Resource, InteractionSummary and the other typed /api/<Key> requests. The documents and discussions it renders are the same data the web app shows. See Seed API.

    Writes are signed on the phone. The comment composer builds a comment blob with the SDK's createComment. It sends the blob with publish, which is the PublishBlobs action of the Seed API.

    Site config comes from the server's /hm/api/config. This is also how the app learns the site's notify service. The notify API gives the order in which the app looks.

Configuration

    Server. The default server is https://dev.hyper.media. Add https://hyper.media or any Seed site on the server screen to use production data.

    App environment. The default is https://hyper.media/hm/api/apps. Override it with EXPO_PUBLIC_SEED_APPS_ENVIRONMENT_URL at build time, or in the app.

    Remote vault. https://hyper.media/vault by default.

Identities and the vault

The app keeps identities in its own vault on the device. That vault is a TypeScript port of the daemon's local vault in backend/storage/vault. It can sync with a remote vault, the Seed service that stores encrypted keys.

The app stores private keys in the platform keychain through expo-secure-store, with the WHEN_UNLOCKED_THIS_DEVICE_ONLY access setting. So the keychain does not copy them to other devices. The web build is for development and tests, and there the secret store uses browser storage.

You get an identity into the app in one of three ways:

    Create a new key on the device.

    Import a 12-word recovery phrase. The derivation matches the daemon: BIP-39 seed, SLIP-10 path m/44'/104109'/0', Ed25519. See Keys.

    Connect a remote vault, https://hyper.media/vault by default. The app runs the same vault connect handshake as the desktop app. Then it syncs identities with the remote vault and merges changes from both sides. The vault page describes the handshake.

You can also import an unencrypted .seedkey file that the desktop app exported. The app cannot import an export with a password, because that needs Argon2id, which the app's JavaScript engine cannot run.

Running it

pnpm mobile:install # npm install inside the app; run pnpm install at the root first pnpm mobile # Expo dev server: scan the QR code, or press w for the web build pnpm mobile:web # web build only pnpm mobile:test # jest unit tests pnpm mobile:typecheck

The ios/ and android/ folders are generated and are not in git. Create them with npx expo prebuild, then run npx expo run:ios or npx expo run:android. Run these commands inside frontend/apps/mobile. Release builds go through Expo Application Services (eas.json). npm run submit builds the iOS app and submits it. The bundle id is media.hyper.seed.mobile and the URL scheme is hm.

The end-to-end tests live in the repository's tests/ package. mobile-web.integration.test.ts drives the web build with Playwright against a real daemon and web app, and mobile-vault.integration.test.ts covers the vault.

Working with it

In the Seed app

The mobile app shares identities with the desktop app in one way only: both connect to the same remote vault. The mobile app does not read the desktop app's local data.

SDK

The app is a working example of the SDK in React Native. The client, createComment, CBOR and signing all run under React Native with a few small patches.

Seed API

Everything the app shows comes from a site's /api/<Key> routes and /hm/api/config. Images come from the site service /hm/api/image/<cid>, which resizes them. See Seed API.

Agents

The Agents screens list your Seed Agents, open sessions and let you chat. They reuse the part of the shared agents code that does not depend on a platform: the signed client, the React Query models, the chat row model and the tool summaries. Only the views are written again for React Native. Configuration says which app environment the app talks to.

For UI work that spends no model tokens, run npm run mock-agents inside frontend/apps/mobile. It serves a fake app environment on http://localhost:3052 with scripted answers. It streams replies, shows tool calls that wait, moves a plan forward and pauses a run to wait for an answer. It does not check signatures and it binds to loopback only. Never deploy it.

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

Attributes
name
The Seed mobile app
summary
The Seed mobile app is the Expo and React Native app for iOS, Android and the web that reads documents and discussions from a Seed site, keeps identities in a vault on the device, and chats with Seed Agents.