Run opencode on Android: a working setup from five weeks on the phone

Drafted with AI help, human-reviewed by The Agent Loop.

Receipts from an actual phone: an S25 Ultra running opencode since 2026-08-25. Versions below are checked as of October 2, 2026.

You don't need a laptop to run a serious AI coding agent. The official opencode docs tell you to install WezTerm or Alacritty and never mention Android once. The binary has no such problem: it is a plain linux-arm64 build, and a phone with a Linux userland runs it fine. I have been doing exactly that for five weeks, through five full environment restarts, and this blog post was written from inside the setup.

The five-line version:

• Termux gives you a Linux terminal on Android; proot-distro gives you an Ubuntu userland inside it.
• opencode's own install script explicitly supports linux-arm64, so the standard one-liner just works.
• opencode itself is a single binary; Node is for the MCP servers and scripts around it.
• The docs' desktop-terminal prerequisite is a habit, not a requirement.
• Four gotchas will bite you anyway: Node platform, RAM, background jobs, and no systemd.

Why the docs don't mention your phone

The opencode docs list prerequisites as "a modern terminal emulator" and name four desktop apps. Windows gets a whole page telling you to use WSL. Android gets nothing. Meanwhile the install script, which I fetched on October 2, maps uname -m from aarch64 to arm64 and accepts linux-arm64 as a supported target right next to linux-x64 (install script).

That gap is the whole tutorial. The agent is a compiled binary for the same ARM instruction set your phone already speaks. What it wants from you is a Linux environment, and Android has one ready: Termux, plus proot-distro, which runs a real distribution without root by translating system calls in user space.

Android phone (12 GB RAM)
  └─ Termux                 Linux terminal for Android
       └─ proot-distro      Ubuntu 26.04 userland (no root)
            ├─ opencode     v1.18.34, single linux-arm64 binary
            └─ MCP servers  exa, firecrawl, playwright (stdio/HTTP)

The stack, with receipts

Every row is from this machine, checked October 2, 2026:

Component	Receipt
Device	Samsung Galaxy S25 Ultra, 12 GB RAM
Kernel	6.17.0-PRoot-Distro
Userland	Ubuntu 26.04 LTS, glibc 2.43
Agent	opencode --version → 1.18.34
Node	v26.4.0 (MCP servers, Playwright, scripts)
Python	3.14.4 (analytics, diagrams)

Docs now carry a banner for a v2 of opencode; this post is the 1.x setup, and every version string above is date-stamped so you can tell what you are reading.

Install path

On the Termux side (Android, not inside the container):

pkg install proot-distro
proot-distro install ubuntu
proot-distro login ubuntu

Inside Ubuntu, first login:

apt-get update && apt-get install -y curl git
curl -fsSL https://opencode.ai/install | bash
opencode --version
1.18.34

The script drops the binary in ~/.opencode/bin and adds it to your PATH. No Node is required for that step. If you ever see this, you're already inside, which is the correct state:

Error: attempted to run proot-distro in a proot session.

Run proot-distro list from Termux if you want to see your installed distro; it refuses to run nested, on purpose.

The four gotchas the docs don't cover

1. Termux's Node can poison the well. Termux ships its own Node package, and some builds report process.platform as android, which Playwright rejects outright. Install a normal Linux arm64 Node inside the Ubuntu userland instead (mine is v26.4.0), and that class of error never appears. This is the reason the agent lives inside proot rather than in raw Termux: everything in there reports linux, and the tooling behaves like it would on any desktop.

2. RAM is the real limit, not CPU. Twelve gigabytes sounds like plenty until you spawn browser automation. Four Chromium tabs under proot sent this box into epoll and futex failures (the kernel calls return "not implemented" through the translation layer), and one runaway log file grew to 64 GB in a morning. The rules I now run by: free -m before starting anything browser-heavy, --concurrency=1 on renders, and never point a long-lived process's stderr at an unbounded file.

3. Background jobs are perishable. A detached setsid job survives a tool timeout but not an environment restart, and I have now buried five of them. Worse, sleep runs on a clock that stops while the phone suspends, so a job armed for 13:00 can wake up three hours late. The working pattern: detach properly, then grep the log after the window and rerun the idempotent script if the receipt is missing. Never trust that the job filled its file.

4. Nothing auto-starts. There is no systemd here. Check with ps before you believe a service is up; MCP servers, browsers, and schedulers all start by hand or from scripts you control. It's less convenient than a laptop, and it makes every failure visible, which I've come to like.

The config that matters

Everything agent-specific lives in one global file, ~/.config/opencode/opencode.json. The part you touch most is the mcp map, which is plain JSON with a command and an environment block:

{
  "mcp": {
    "exa": {
      "type": "local",
      "command": ["/usr/local/bin/exa-mcp-server"],
      "environment": { "EXA_API_KEY": "<your key>" }
    },
    "firecrawl": {
      "type": "local",
      "command": ["/usr/local/bin/firecrawl-mcp"],
      "environment": { "FIRECRAWL_API_KEY": "<your key>" }
    }
  }
}

Two rules I learned the hard way: the file holds live API keys, so keep it readable by you only and out of any git repo, and if your MCP tools suddenly vanish, check this file before you reinstall anything. A broken config has wiped this box's tool list once already, and the Hermes config next door was the copy that rebuilt it.

What the phone gives you that the laptop doesn't

The fun part is that the device you are automating is the device in your hand. adb over wireless debugging controls the phone itself, so the same terminal that runs the agent can drive its host. Pair it with a monitor through DeX and the setup becomes a workstation that fits in a pocket. The agent session also survives screen locks and app switches the way a terminal multiplexer does, not the way mobile apps do.

Bottom line: the "AI coding agent needs a laptop" claim is a documentation habit, not a technical one. Termux plus proot-distro plus the stock linux-arm64 installer is a boring, copy-pasteable path to running opencode on Android, and five weeks of daily use say the four gotchas are the entire maintenance surface.

FAQ

Is this an official opencode setup?
No, and I'm not affiliated. It is what one user's phone has run since August 2026, with versions you can verify against the table above.

Does it work on low-RAM phones?
The agent itself is lightweight; the browser-heavy workloads are not. Under 8 GB I would expect the memory gates in gotcha two to fire often, and I have not tested below 12 GB myself.

Can I use this for real work, or is it a demo?
Every post in this series, including this one, was drafted, verified, and published from the setup, along with the analytics dashboard and the scheduled jobs that keep it running.

Related on The Agent Loop

• Your agent's tests pass. That's the problem. (what you run once the agent is on your machine)
• Why your MCP approval gate never fires (the MCP layer from the diagram, one layer down)
• Your agent's cost problem isn't the model. It's the loop. (what the loop costs when it runs on your hardware)

Sources

1. opencode docs: Intro and prerequisites
2. opencode install script (fetched 2026-10-02; linux-arm64 support at script lines 102-110)
3. Termux
4. proot-distro (Termux wiki)
5. opencode MCP server docs

If this saved you a laptop, tap the unicorn below; one click, and it is the only metric Dev.to shows me. Follow The Agent Loop for the rest of this series.

Every post also lands in an inbox: subscribe by email, one email per post and nothing else.

---

What would you run first if your entire dev environment fit in your pocket? A CI script, a bot, the blog itself? Reply below.