HELP · FAQ

Read this before opening a terminal.

Install, pairing, relay authentication, optional TLS, commands and release signing. If the answer is not here, open an issue with logs and reproduction steps.

Install & pairing

Which APK should I install?

Use android-arm64-v8a.apk on real devices and android-x86_64.apk on x86_64 emulators. A mismatched ABI usually fails during installation.

The phone cannot connect, but opencode is running.

Run ./ocremote direct 0.0.0.0:8787 on the host, then ./ocremote pair. A loopback-only direct listener is never offered to phones. Then check the computer firewall and the phone network.

What if the pairing code expires?

Run ./ocremote pair on the computer and add the host again. Codes expire after five minutes by default; use --ttl to change it.

Why compare the host fingerprint?

The fingerprint identifies the host Noise static key. Comparing it prevents connecting to an impersonated host. Do not continue if it differs.

Sessions & commands

Which slash commands work on the phone?

Core commands include /models, /agents, /mcps, /skills, /variants, /sessions, /new, /compact, /status, /diff and /help. Server commands such as /init, /review and /goal still go to opencode.

Why are some commands greyed out?

They require a terminal, editor, worktree manager or desktop surface. The phone marks them unavailable instead of sending a request that returns 404.

What happens if I send while the agent is running?

The message is queued and sent when the current run ends. The composer shows the queue and lets you cancel pending items.

Do I need to refresh after another client changes agent or model?

No. The phone refreshes the current session from the event stream, and changes made on the phone are emitted for other clients too.

Relay authentication & optional TLS

Is a relay required?

No. Prefer direct LAN. Use a relay when the phone and computer are on different networks or need NAT traversal. It forwards encrypted frames only.

Relay authentication fails.

Check that the relay is reachable, the host ran ./ocremote relay with the correct IP:port, and --max-hosts is not full. A relay upgrade or database reset invalidates old identities.

Can I still use TLS?

Yes. TLS is an optional transport layer; Noise NK authentication and encrypted control frames do not depend on it. A public CA needs no extra configuration. Only a self-signed wss:// relay needs --relay-ca on the host plus the CA in the Android system store.

Can the relay read my code?

Not application data. It sees room, subject identity, timing and frame size metadata. Sessions, files and tool payloads stay inside Noise ciphertext.

Release & builds

Why is the APK signed with a debug keystore?

The current release still uses the Expo debug keystore for test installs. Replace it with a production keystore and rebuild before distributing to end users.

Is there a Linux arm64 host build?

Yes. ocremote-host-1.0.1-linux-arm64.tar.gz bundles arm64 Bun and sherpa-onnx. The x64 host uses linux-x64.

How do I verify a download?

Download SHA256SUMS from the same release, place it beside the artifacts and run sha256sum -c SHA256SUMS.