Skip to content
Moko

Install & setup

Getting Moko running takes a few minutes. The installer brings everything it needs — including a private copy of Python — so the only prerequisite is a terminal. Works on macOS, Linux, and Windows.

1. Install

Section titled “1. Install”
Terminal window
# macOS / Linux
curl -fsSL https://mokomoko.ai/install.sh | sh
Terminal window
# Windows
irm https://mokomoko.ai/install.ps1 | iex
  • Safe by default. Installs the moko command into your user directory — never as root, never touching system files.
  • Pin a version. Set MOKO_VERSION=v0.1.0 before the command for a reproducible setup. Otherwise you get the latest release.

From source

Section titled “From source”

With uv, install the CLI straight from the repo:

Terminal window
uv tool install --from "git+https://github.com/huesy/moko.git#subdirectory=apps/agent" moko

Or work inside a clone:

Terminal window
cd apps/agent
uv sync
uv run moko --help

2. Set up

Section titled “2. Set up”
Terminal window
moko setup

A warm, full-screen walkthrough — a handful of steps with a progress trail across the top — that asks for:

  • Your language — Moko greets you, and talks with you, in it. The setup screens themselves are fully translated for a few languages and fall back to English for the rest; either way Moko converses in your language.
  • The terms — a short, plain-language note on how Moko works: it never lies to you, your data stays on your machine, and it asks before doing anything that reaches the outside world. You accept before going on.
  • Your country — Moko is always time-aware, and everything it does is stamped in your time. Your country sets the timezone (with a quick city pick where a country spans several). Nothing is hard-coded; it learns this here.
  • Your sleep window — the quiet hours when Moko won’t message you and instead dreams: the night it spends consolidating what it learned.
  • Your LLM provider — bring your own. Anthropic, OpenAI, OpenAI-compatible endpoints (including xAI Grok), or a Claude/Grok subscription via OAuth (moko login) instead of a metered API key.
  • Senses (optional) — point image, voice, and video at their own providers if you want, so Moko can send and make media.
  • How you’ll talk — connect Telegram right here, so it’s all one sitting (more channels are on the way).

Store credentials with moko secret set, then sanity-check:

Terminal window
moko status     # how Moko is configured
moko doctor     # scan what's set up, running, or needs attention

3. Pair Telegram

Section titled “3. Pair Telegram”

Talk to Moko from your phone. Pairing is secured by a one-time code, so a stranger who finds the bot can’t bind it.

Terminal window
moko pair

Follow the prompt: message your bot, confirm the code, and from then on only you are heard. Prefer the terminal? Just run moko chat.

4. Bring Moko online

Section titled “4. Bring Moko online”

Run Moko as a background service so it’s always there — surviving restarts, ticking its heartbeat, and dreaming overnight.

Terminal window
moko service install     # set up the background service
moko service start       # bring it online
moko service status      # check on it
moko service logs        # tail the logs

moko setup offers to do this at the end, so in practice it usually just works.

5. Watch Moko’s mind (optional)

Section titled “5. Watch Moko’s mind (optional)”
Terminal window
moko monitor

Opens the local monitor — a live window into Moko’s feed, thoughts, subjects, curiosities, commitments, and dreams. Served on 127.0.0.1; never leaves your machine.

Where everything lives

Section titled “Where everything lives”
  • One place. Moko’s entire mind — the graph, your config, logs, and secrets — lives under ~/.moko/, never in a repo or the cloud.
  • One file. The mind itself is a single SQLite file. Snapshot it any time with moko snapshot, restore with moko restore.