opencode2-mobile

A native Expo client for the OpenCode V2 HTTP API. The app runs on iOS and
Android and connects directly to a user-configured OpenCode server. OpenCode V1
is out of scope.

opencode2-mobile is an independent mobile client for OpenCode. It is not built by or
affiliated with the OpenCode team or Anomaly.

Mobile workflow

Keep track of active and blocked sessions across followed projects.

Session inbox with active work and a session that needs input

Coding session with a completed background subagent

Coordinate parent and child agent work.

Pending shell permission with allow and reject controls

Handle blocked permissions from the phone.

Pending OpenCode form with a read-only command choice

Answer structured forms without returning to the terminal.

Project documents

Architecture

apps/mobile contains the Expo application. packages/opencode-adapter is the
only package that imports @opencode/client; it never imports the Node-only
service entrypoint. The phone connects directly to OpenCode over HTTPS or
explicitly approved private-network HTTP.

Optional remote attention uses a separate V2 plugin and self-hosted notification
broker. The broker is not an OpenCode proxy. Its local pairing CLI or the
same-host OpenCode /pair flow accepts the OpenCode credential long enough to
create an encrypted, short-lived bootstrap challenge. Normal notification
processing never uses the credential. See the notification setup document for
the signed-build workflow and pairing trust model.

The app supports saved connections, followed projects, session management,
paginated transcripts, text prompts, permission and form responses, encrypted
drafts, and optional self-hosted permission, form, and session-completion
notifications. It stores Basic or Bearer
credentials only in SecureStore. TODO.md tracks the remaining product and
device-verification work.

Development

Use Node.js 26.7.0 (fnm use, nvm use, or another version manager) and pnpm
11.21.0. Node 26 does not bundle Corepack, so install the pinned pnpm release if
it is not already available:

npm install --global [email protected]
pnpm install --frozen-lockfile
pnpm go

A clean clone uses generic native identifiers and does not require an Expo or
Firebase account. Copy apps/mobile/config/deployment.example.json to the
ignored apps/mobile/config/local/deployment.json before creating a
deployment-specific signed build. See
deployment configuration for EAS, Firebase, APNs, and
FCM setup. Never store credentials in Expo app configuration.

pnpm go starts Expo Go for devices on the same LAN. pnpm dev instead
advertises this machine's Tailscale address and requires an installed,
authenticated Tailscale CLI. Scan either QR code with the App Store Expo Go app.

The project uses SDK 54 so it opens in the Expo Go build currently distributed
through Apple's App Store. pnpm dev:client starts Metro for an installed
development build. Generate and launch native projects with pnpm android when
the Android SDK and JDK are installed or, on macOS with Xcode and CocoaPods,
pnpm ios. Expo config plugins own the ignored android and ios directories.

Preview distribution

The preview EAS profile produces standalone release-mode builds for device
testing. These builds use the preview EAS Update channel and do not need Metro.
Configure your own EAS project first, then run EAS commands from the app
directory:

pnpm check
pnpm native:doctor
cd apps/mobile
pnpm dlx [email protected] whoami

Build an installable APK for Android with:

pnpm dlx [email protected] build --platform android --profile preview

Open the resulting EAS build URL on the Android device. Android may ask the user
to allow the browser to install apps from unknown sources.

An iPhone must be registered before its first ad hoc build. This requires Apple
Developer Program access:

pnpm dlx [email protected] device:create
pnpm dlx [email protected] build --platform ios --profile preview

Choose your Expo account and Apple team during device registration. Use the
website registration method and open its URL on the iPhone. During the build,
you may let EAS manage the distribution certificate and ad hoc provisioning
profile, and include the registered iPhone.

Install the app from the resulting EAS build URL. On iOS, enable Developer
Mode under Settings > Privacy & Security, restart the phone, and confirm
the setting before launching OpenCode2 Mobile. Registering another iPhone requires a new
build or a re-signed build whose provisioning profile includes that device.

Your EAS project dashboard lists its builds and installation links.

Preview updates

For hourly OpenCode release checks, cloud repair PRs, and automatic EAS
publication, configure the automatic update workflow.

EAS Update handles JavaScript, styling, and bundled asset changes without a new
native build. Validate the repository, then publish to the channel used by the
installed preview builds:

pnpm check
cd apps/mobile
pnpm dlx [email protected] update --channel preview --environment preview \
  --message "Describe the update"

The installed app downloads an available update when it launches and checks
again when foregrounded. Settings and connection-failure screens offer a manual
check. A downloaded update offers a restart after saving session drafts, and
also applies on the next cold start. Expo SDK changes, native dependency changes,
config plugin changes, permissions, icons, and other native configuration still
require new Android and iOS builds. Increment the app version in app.config.ts
before such a build so the appVersion runtime policy cannot send incompatible
updates to an older binary.

Run the complete repository checks with:

pnpm check
pnpm native:doctor

The connection form accepts an origin such as https://host.example:4096.
Cleartext Tailscale or LAN HTTP requires explicit approval in the app. Never put
credentials in source files, environment files, URLs, or command history.

References

OpenCode 2 and its client are currently beta. API and client contracts may
change before the stable release.

License

opencode2-mobile is available under the MIT license. Dependencies and bundled
data retain their own licenses; see third-party software.