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 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 |
|---|---|
| The entry point and providers. |
| The screen stack. |
| Server select, account, identities, vault, vault connect, document, comment, notifications. |
| The React Native views for blocks, embeds, query blocks and discussions, and the comment composer. |
| The Seed API client for the chosen server and its |
| The vault on the device: the encrypted envelope, secure key storage, vault connect and remote sync. |
| The agents screens. |
| The signed client for the notify service. |
| 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:typecheckThe 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.
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
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