Docs
Docs menu

Quick start

Run a node on your laptop, bring a repository from GitHub, add a runner and have an agent open a pull request.

This page takes you from nothing to a pull request an agent wrote, on a repository you already have on GitHub. Everything runs on your own machine. You need Docker, a GitHub account with write access to the repository, and a coding agent on a Linux or macOS machine: Claude Code, Codex or Gemini CLI with your usual login or an API key, or any other agent you can start from a command line.

For a node your team will use, follow Install instead: it covers HTTPS, a domain and the Compose bundle.

Start the node#

The node is one container image with the web UI built in. Run it with a volume for its data and the URL you’ll open it at:

docker run -d --name moru \
  -p 7070:7070 \
  -v moru-data:/data \
  -e MORU_PUBLIC_URL=http://localhost:7070 \
  ghcr.io/webstonehq/moru-node:latest
  • /data holds everything the node keeps: repositories, keys, accounts and settings. Keep the volume and you keep the node.
  • MORU_PUBLIC_URL is the address people use. It goes into clone URLs, sign-in links and the commands the UI shows you. Without it those say http://0.0.0.0:7070, which nobody can open.

Create the first admin#

A new node has no accounts. On its first start it prints a one-time setup link to its log. This prints the link:

docker logs moru 2>&1 | grep 'setup#code='
    http://localhost:7070/setup#code=mrs_…

If you open http://localhost:7070 first, the node shows you the same command.

Open the whole link, including the part after #. On Create the first admin, pick a handle (lowercase letters, digits, ., _ and -) and a password of at least 12 characters, then click Create admin and sign in.

The link works once. If you restart the node before using it, the old link stops working and the logs show a new one. After this, you sign in at /login with your handle and password.

You land on the repository list. On a new node, Getting started at the top lists the four steps that follow and ticks each one off as you go; it goes away once they’re all done.

Bring your repository from GitHub#

Choose Import from GitHub. On a node at localhost, the page offers Link a repository: GitHub can’t send people back to localhost, which a GitHub App needs, so you link one repository at a time. It stays on GitHub, Moru follows its branches, and approved changes go back as pull requests.

A public repository needs nothing else to start. Under GitHub repository, type its owner/name on GitHub, leave Token empty and choose Follow without a token. Moru asks for a token later, when there’s a change to send back.

A private repository needs a token before Moru can fetch it:

  1. Under GitHub repository, type its owner/name on GitHub.
  2. Get a token. If you use the GitHub CLI, gh auth token prints one. It reaches every repository your account can, and the node keeps it on its disk. For a token that reaches only this repository, choose Create a token on GitHub: GitHub’s token form opens filled in, with the permissions Moru needs. Under Repository access, choose Only select repositories and pick the repository, then Generate token and copy it.
  3. Paste it under Token and choose Link repository.

The repository opens right away; the first fetch from GitHub runs in the background. GitHub covers linked repositories in full, including GitHub Apps for a node with a public address.

Add a runner#

Agents run on runners, not on the node. Your laptop works. The runner runs agents as the user you start it as, with no sandbox, so the agent can reach whatever that user can. Where to run a runner helps you pick the machine.

Choose Add a runner in Getting started (or open Runners from the account menu). The page shows one command, with a one-time code in it. Run it on the machine, as the user agents should run as:

curl -fsSL http://localhost:7070/install-runner.sh | sh -s -- --code mrr_… --name laptop --run

It installs moru-runner into ~/.local/bin, registers it, and starts it. The page shows when the runner comes online. Agents use the logins already on that machine: if claude, codex or gemini works in your terminal, it works in the runner. Otherwise set a key first, such as ANTHROPIC_API_KEY, CODEX_API_KEY or GEMINI_API_KEY. Codex and Gemini CLI are offered when they’re installed, and Agents shows how to add any other agent. The runner keeps its cache in the directory you ran the command in: start it again from there with moru-runner run. Add a runner has the details.

Ask an agent for something#

In your repository, click New request. A repository’s first request offers a few small tasks to start from, such as Add tests for an untested part of the code: pick one, or write your own title, details and acceptance criteria.

Leave Who should do this? on Single agent. Under Agent, pick the one you use: claude-sonnet is the default, and codex and gemini are there too. Then click Start agent. The request page shows the agent’s log as it works, and its change when it submits.

Review it and ship it#

Open the change, read the diff, and click Approve r1. If you followed the repository without a token, the page says so: choose Add a token and paste one (the steps above for a private repository). On a repository linked to GitHub, Open a pull request for r1 rebases the change onto GitHub’s branch, pushes it as moru/<change-id> and opens a pull request. Merge it on GitHub as usual, and the change in Moru shows as merged.

That’s the whole loop. Next time, try a Bake-off: several agents do the same task and you pick the best result.

No GitHub? Push to Moru instead#

To keep a repository on the node itself, use the New repository panel on the right of the repository list. Untick Add a README if you’re about to push an existing project.

git doesn’t use your password. It uses an access token: open the account menu, choose Account, and under Access tokens for git create one. Copy it; it’s shown only once. An access token lets git fetch and push as you, and nothing else.

An empty repository opens on its Overview tab, which shows the commands with your node’s URL filled in:

git remote add moru http://mira@localhost:7070/git/mira/timetable.git
git push moru main

When git asks for a password, paste the access token. The Clone button in the repository header copies the clone command, and a public repository can be cloned without any credentials.

Read Changes for how proposing works, and Reviewing and merging for protected branches.

Next steps#

Command menu
Search for a page, repository, change or request, or run a command