Monaw

Monaw Agent is a local-first Windows desktop AI agent for people who want an assistant that can work inside their machine, not just answer questions.

Monaw combines a calm chat interface with controlled access to local files, shell commands, browser automation, computer-use actions, memory, scheduled tasks, MCP servers, and an optional Telegram bridge. You bring your own model keys, choose the provider and permission profile, and keep runtime data under your local Monaw folder.

It is built for users who have outgrown basic chatbots but do not want a heavyweight agent setup that burns through context, hides what it is doing, or turns every task into a large token bill. Monaw focuses on practical desktop automation: give it a task, review tool access, and let it work with your Windows workspace under your control.

Monaw currently targets Windows. macOS has not been tested yet.

Why Monaw

• Desktop-first workflow. Work with files, browser pages, local commands, app windows, and scheduled follow-ups from one agent UI.
• Local control. Runtime data, memory files, logs, browser artifacts, and the default workspace stay under your local Monaw folder.
• Bring your own models. Use OpenAI, DeepSeek, or Google Gemini through your own API keys.
• Context discipline. Memory, context tracking, and compression help keep useful knowledge available without blindly stuffing every conversation.
• Tool permissions. Choose sandbox, approval, and access settings before the agent performs higher-impact actions.
• Windows-friendly setup. The one-click setup prepares Python, Node, backend packages, and frontend packages for normal Windows users.

What Monaw Can Do

Chat With Your Preferred Models Use OpenAI, DeepSeek, or Google Gemini through your own API keys, while keeping conversations in one local desktop workspace.	Work Inside Your Windows Desktop Ask Monaw to inspect files, run local commands, automate browser flows, and coordinate computer-use actions with visible tool access.
Remember Useful Context Store long-term memory locally and use context tracking plus compression so the agent can stay helpful without wasting tokens.	Schedule Follow-Up Work Run scheduled tasks with history for reminders, recurring checks, delayed follow-ups, and automation that should happen later.
Connect Tools Through MCP Add MCP servers from Settings, use browser automation through browser-use, and optionally connect a Telegram bot bridge.	Control What The Agent Can Do Choose permissions, approvals, access grants, and sandbox settings before Monaw performs higher-impact actions.

Requirements

• Windows 10 or 11. macOS is not tested yet.
• Git.
• Node.js 18+ and npm. The one-click setup can install this for you.
• Python 3.10+; Python 3.11 is recommended. The one-click setup can install Python 3.11 for you.
• Conda or Python venv for manual setup. The one-click setup creates backend\.venv for you.
• Optional: Docker Desktop for stronger shell-command sandboxing.

Install

Clone the repo:

git clone https://github.com/kailiang0120/monaw.git
cd monaw

Option A: One-Click Windows Setup

For normal Windows users, double-click setup.bat:

setup.bat

The setup launcher will:

• Install Python 3.11 with Windows Package Manager if Python is missing.
• Install Node.js LTS with Windows Package Manager if Node/npm is missing.
• Create backend\.venv.
• Install Python packages from backend\requirements.txt.
• Run npm install in frontend.

When setup finishes, double-click start.bat:

start.bat

If setup fails, check:

%USERPROFILE%\.monaw\runtime\setup\setup.log

Option B: Manual Developer Setup

Create and install the Python backend environment first.

Conda. The launcher tries to activate a Conda environment named agent:

conda create -n agent python=3.11 -y
conda activate agent
cd backend
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cd ..

Local venv. Monaw auto-detects backend\.venv:

cd backend
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cd ..

Install the frontend packages:

cd frontend
npm install
cd ..

Start Monaw:

.\start.bat

First-Run Setup

Open Settings in Monaw Agent and configure only the services you use:

• DeepSeek API key. Recommended.
• OpenAI API key.
• Google API key, if using Gemini or vision fallback.
• Tavily API key, if using web search tools.
• Telegram bot token and allowlist, if using Telegram.
• Model provider, model, and reasoning effort.
• Permission profile and access grants.
• Sandbox mode.
• Browser automation mode.
• MCP servers.
• Memory settings.

Normal desktop use does not require editing .env. The Settings screen saves runtime configuration locally.

Daily Use

Start the app from the repo root:

.\start.bat

The launcher starts the desktop app and exits after startup succeeds.

If you use Conda, keep the environment named agent, or activate your preferred environment before launching.

If you use a custom Python path, set AGENT_PYTHON_PATH before launching:

$env:AGENT_PYTHON_PATH = "C:\path\to\python.exe"
.\start.bat

Local Data

Runtime app data is local. Monaw keeps user-visible data under:

%USERPROFILE%\.monaw\

Main folders:

%USERPROFILE%\.monaw\runtime\        settings, database, logs, Electron store
%USERPROFILE%\.monaw\workspace\      default agent working directory
%USERPROFILE%\.monaw\browser\        managed browser profile, downloads, screenshots, traces
%USERPROFILE%\.monaw\memory\         long-term memory markdown files

Settings, config, logs, browser downloads, screenshots, managed profiles, traces, memory, and the default agent workspace all stay under this folder.

You can change the main data folder with MONAW_HOME or AGENT_HOME, the runtime folder with AGENT_RUNTIME_DIR, the default agent workspace with AGENT_WORKSPACE_DIR, and the memory folder with AGENT_MEMORY_DIR.

Feature Docs

Memory is configured in Settings -> Memory. Memory files are local markdown files and can be edited from the app. See docs/memory.md.

Browser automation is configured in Settings -> Browser. See docs/browser-automation.md.

MCP servers are configured in Settings -> MCP. See docs/mcp.md.

Scheduled tasks are configured in the app when scheduling is enabled. See docs/scheduling.md.

Telegram is optional. Keep the bot token private and keep the allowlist narrow. See docs/telegram.md.

Permissions, approvals, access grants, and sandbox settings are configured in Settings. See docs/permissions.md and docs/sandboxing.md.

Troubleshooting

If start.bat fails before the app opens, check:

%USERPROFILE%\.monaw\runtime\launcher\vite.log
%USERPROFILE%\.monaw\runtime\launcher\electron.log

If the app opens but cannot connect to the backend, check:

%USERPROFILE%\.monaw\runtime\

If backend imports fail, reinstall backend packages in your Python environment:

cd backend
python -m pip install -r requirements.txt

If frontend startup fails, reinstall frontend packages:

cd frontend
npm install

If Vite reports port 5275 is already in use, stop the existing Vite process or reuse it intentionally.

Developer Docs

Developer setup, architecture, module map, testing, and packaging notes are in docs/development.md.

Repository Status

This public repository is currently intended for cloning, local use, and code review. External contributions are not being accepted yet; issues, pull requests, and Discussions may stay disabled until the project is ready for community maintenance.

License

Apache License 2.0. See LICENSE.