README
¶
Moa
A self-hosted coding agent for the machine where your code lives — usable from desktop or phone.
Quick start · Security · Documentation
“I did not build Moa to replace my computer. I built it because I could not always be at one.”
At some point my life stopped giving me long stretches at a desk. Some days I had two hours at the computer; some days, one. I tried the existing answers — remote-control apps for coding agents got me halfway, but sooner or later something always forced me back to the physical machine: a stuck process, an environment to bring up, a result I could not see from my phone.
So I built Moa. The agent lives on the machine where my code, repositories, and tools already are, and I steer it from wherever I am. In a normal day it works in a Git worktree, brings up the project's Docker environment, runs the builds and tests, drives the app with Playwright and sends me screenshots as evidence, or exposes a port so I can try the result myself. When a 500 shows up in production, it investigates and we fix it together — from my phone.
As I write this, I have not opened my laptop in three weeks, and I am putting in full days of real development work.
The point is not to turn a phone into a tiny laptop. It is to stay in the loop while real development work happens on the machine built for it.
Moa separates where the agent works from where you steer it. Run it on a workstation or development server that already has your repositories and toolchain, then open the same workspace in a browser. Start a task at your desk, check its progress from your phone, answer a permission request, or redirect the session without moving the project to another machine.
An active coding session on desktop: conversation, tool work, and results stay together.
The development machine stays put. You do not have to.
A phone is not the best place to edit a codebase line by line. It is a very good place to stay in the loop.
Moa's mobile interface lets you return to the same server-side sessions, see what the agent is doing, answer questions or permission prompts, send new direction, and stop or resume work. The repository, dependencies, credentials, and running processes remain on the development machine.
The same running session on an iPhone — progress and decisions without reopening the laptop.
See the work, not just a chat transcript
Agent work quickly becomes more than one stream of messages. Moa can keep several sessions open in a pane grid, use a different model for each one, and show tool activity, delegated agents, usage, and attention state alongside the conversation.
The goal is not to make you watch more logs. It is to make it obvious what is running, what finished, and what needs you.
Parallel sessions with live telemetry and delegated work visible in the Live Dock.
Why self-host the agent?
Moa runs on infrastructure you control rather than uploading your repository to a Moa-operated service.
- Use the environment you already have. The agent works with the repository, shell, compilers, containers, and project tools installed on the host.
- Choose your own access boundary. Keep it on localhost, reach it through a private network such as Tailscale, or place it behind your own authenticated reverse proxy.
- Keep operational state on your machine. Session history, configuration, credentials, and project memory are stored by your Moa installation.
- Use the provider you choose. Moa talks to Anthropic or OpenAI from your machine and does not add a separate hosted agent service in between.
Self-hosted does not mean offline: prompts, selected code or file content, and tool results needed by the model are sent to the provider you configure. Review that provider's data policies and use Moa's permission and path controls for the level of access you want.
Built for a real development loop
- Work with the whole project. Moa can inspect and edit files, run shell commands, execute tests, search the repository, and use the development tools available on the host.
- Stay in control. Choose
ask, AI-evaluatedauto, or permissiveyolopermissions, combine them with path scoping, and use checkpoints, budgets, and run limits. - Delegate and parallelize. Run multiple sessions or let an agent spawn synchronous or asynchronous subagents whose activity can be inspected live.
- Exchange real artifacts. Attach images, PDFs, source files, and other inputs; the agent can return downloadable files, rich Markdown, images, and sandboxed HTML previews.
- Bring your own workflow. Add MCP servers, custom script tools, verification commands,
reusable skills, and project instructions through
AGENTS.md.
Delegated work stays inspectable: each subagent has its own conversation, tools, and result.
For the complete capability reference, see the Overview, Tools, and Configuration documentation.
Use the provider you already have
Moa supports Anthropic and OpenAI.
You can authenticate with a Claude Pro or Max or ChatGPT Plus/Pro subscription through OAuth, without configuring a separate API key for the main agent. Anthropic and OpenAI API keys are supported as well. Model availability and usage limits remain those of the provider account you use.
Quick start
Install the latest release:
curl -fsSL https://letmoa.run/install.sh | sh
# or with Homebrew:
brew install e-aleixandre/tap/moa
Prebuilt binaries are also available from
GitHub Releases, and moa update
replaces an installed binary with the latest release. To build from source,
you need Go 1.25+ and Node.js/npm for the embedded web frontends:
git clone https://github.com/e-aleixandre/moa.git
cd moa
make fe-install
make build
# → ./bin/moa (put it in your PATH, or use ./bin/moa in the commands below)
Authenticate with an existing subscription:
moa --login anthropic # Claude Pro/Max OAuth
moa --login openai # ChatGPT Plus/Pro OAuth, or choose an API key
Or provide an API key directly:
export ANTHROPIC_API_KEY="..."
# or:
export OPENAI_API_KEY="..."
Start the web UI:
moa serve
# → http://127.0.0.1:8080
To reach Moa from a phone, put the server and phone on the same private network. For example, with Tailscale:
export MOA_SERVE_TOKEN="<a-long-random-secret>"
./bin/moa serve --host 0.0.0.0
Open the server's Tailscale IP from the phone. See the
Web UI security guide for the token URL, MagicDNS
--allowed-hosts, TLS, and reverse-proxy guidance.
For complete installation, authentication, and first-run instructions, see the Quickstart.
Security
moa serve binds to 127.0.0.1 by default, but it does not enable authentication by
default. Anyone who can reach an unauthenticated Serve port can control its agents.
For remote access:
- Prefer localhost, Tailscale, or another private network boundary.
- Set
--tokenorMOA_SERVE_TOKENin addition to that boundary. - Configure
--allowed-hostswhen accessing Moa through a hostname. - Use TLS when the deployment or paired-device flow requires it.
- Do not expose an unauthenticated Moa port to a network.
The token is defense in depth, not a replacement for an appropriate network boundary. Read the full security documentation before exposing Serve beyond localhost.
Prefer the terminal?
The browser, TUI, and headless CLI share the same agent core and session model.
./bin/moa # interactive TUI
./bin/moa -p "fix the tests" # one-shot, headless
See TUI Usage and the CLI Reference.
Documentation
For installation details, configuration, tool behavior, limits, and security guidance, see the
full documentation in docs/:
| Document | Reference |
|---|---|
| Overview | Capabilities, interfaces, runtime flow, and storage |
| Quickstart | Requirements, build, authentication, and first run |
| Web UI | Serve, panes, mobile use, attachments, voice, and security |
| CLI Reference | Commands, flags, model aliases, and examples |
| TUI Usage | Slash commands, keybindings, and interactive workflows |
| Configuration | Config files, permissions, sandboxing, models, and MCP |
| Tools | Built-in tools, custom tools, subagents, and verification |
| Architecture | Package map, event bus, and runtime design |
| Releases | Versioning, release process, and update checks |
License
Moa is available under the MIT License.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
moa
command
|
|
|
pkg
|
|
|
askuser
Package askuser provides the ask_user tool that lets the agent ask the user one or more questions and block until they respond.
|
Package askuser provides the ask_user tool that lets the agent ask the user one or more questions and block until they respond. |
|
attachment
Package attachment provides durable, content-addressed blob storage for session attachments.
|
Package attachment provides durable, content-addressed blob storage for session attachments. |
|
attention
Package attention implements the Attention Service: a server-side component that consumes the event bus of every active moa session and produces a priority-ordered "attention queue" of items already written for the ear.
|
Package attention implements the Attention Service: a server-side component that consumes the event bus of every active moa session and produces a priority-ordered "attention queue" of items already written for the ear. |
|
auth
Package auth handles credential storage and OAuth flows for AI providers.
|
Package auth handles credential storage and OAuth flows for AI providers. |
|
autotitle
Package autotitle generates short, human-readable session titles from a conversation using a cheap LLM call.
|
Package autotitle generates short, human-readable session titles from a conversation using a cheap LLM call. |
|
bootstrap
Package bootstrap wires up a complete agent session: tool registry, MCP, permissions, subagents, plan mode, skills, verify, and system prompt.
|
Package bootstrap wires up a complete agent session: tool registry, MCP, permissions, subagents, plan mode, skills, verify, and system prompt. |
|
bus
Package bus provides a typed event bus for decoupling agent, TUI, and serve layers.
|
Package bus provides a typed event bus for decoupling agent, TUI, and serve layers. |
|
checkpoint
Package checkpoint provides file-level undo for agent turns.
|
Package checkpoint provides file-level undo for agent turns. |
|
clipboard
Package clipboard provides system clipboard image reading.
|
Package clipboard provides system clipboard image reading. |
|
compaction
Package compaction summarizes old conversation turns to reduce context size.
|
Package compaction summarizes old conversation turns to reduce context size. |
|
files
Package files provides reusable file scanning and filtering logic.
|
Package files provides reusable file scanning and filtering logic. |
|
git
Package git provides lightweight git metadata for the agent's system prompt.
|
Package git provides lightweight git metadata for the agent's system prompt. |
|
goal
Package goal implements an autonomous maker→verifier loop ("goal mode").
|
Package goal implements an autonomous maker→verifier loop ("goal mode"). |
|
jsonutil
Package jsonutil provides utilities for working with JSON streams.
|
Package jsonutil provides utilities for working with JSON streams. |
|
memory
Package memory provides cross-session memory persistence as a set of typed, single-fact files with a lightweight frontmatter header.
|
Package memory provides cross-session memory persistence as a set of typed, single-fact files with a lightweight frontmatter header. |
|
permission
Package permission mediates tool execution approvals between the agent loop and the TUI.
|
Package permission mediates tool execution approvals between the agent loop and the TUI. |
|
planmode
Package planmode implements a plan-then-execute workflow.
|
Package planmode implements a plan-then-execute workflow. |
|
provider/openai
Package openai implements core.Provider for the OpenAI Responses API.
|
Package openai implements core.Provider for the OpenAI Responses API. |
|
provider/retry
Package retry provides HTTP retry logic with exponential backoff for LLM provider API calls.
|
Package retry provides HTTP retry logic with exponential backoff for LLM provider API calls. |
|
provider/sseutil
Package sseutil provides shared utilities for SSE stream handling across LLM provider implementations.
|
Package sseutil provides shared utilities for SSE stream handling across LLM provider implementations. |
|
pulsebrief
Package pulsebrief generates a short, structured status summary of a session from its conversation using a cheap same-vendor LLM call.
|
Package pulsebrief generates a short, structured status summary of a session from its conversation using a cheap same-vendor LLM call. |
|
release
Package release contains build metadata and best-effort release update checks.
|
Package release contains build metadata and best-effort release update checks. |
|
schedule
Package schedule provides durable one-shot schedule records.
|
Package schedule provides durable one-shot schedule records. |
|
serve
Package serve provides an HTTP/WebSocket server for managing multiple agent sessions through a web dashboard.
|
Package serve provides an HTTP/WebSocket server for managing multiple agent sessions through a web dashboard. |
|
session
Package session manages persistent conversation sessions.
|
Package session manages persistent conversation sessions. |
|
sessioncheckpoint
Package sessioncheckpoint provides the single ephemeral handoff slot for a session.
|
Package sessioncheckpoint provides the single ephemeral handoff slot for a session. |
|
tasks
Package tasks provides a standalone task tracking system.
|
Package tasks provides a standalone task tracking system. |
|
usage
Package usage fetches Claude subscription plan usage from Anthropic's OAuth usage endpoint — the same data the Claude Code CLI shows via /usage (5-hour session window, weekly window, and pay-as-you-go "extra usage").
|
Package usage fetches Claude subscription plan usage from Anthropic's OAuth usage endpoint — the same data the Claude Code CLI shows via /usage (5-hour session window, weekly window, and pay-as-you-go "extra usage"). |