Skip to content
mango·agentby Mangosteen Studio
Walkthrough · Start here

Run Mango Agent locally

Clone the repo, start every service with Docker, load the example seed and open the panel.

about 15 min (estimate) 5 steps
Before you start
  • Docker (Desktop or Engine with Compose v2)
  • uv for Python 3.13
  • Node 22 with pnpm
  • Optional: a Gemini API key from Google AI Studio
Your progress
0%0 of 5 steps
  1. 1Clone and install
  2. 2Choose an LLM provider
  3. 3Start the stack
  4. 4Load the example seed
  5. 5Try it

1Clone and install#

bash
git clone https://github.com/Mangosteen-Studio/mango-agent.git
cd mango-agent
make setup   # installs backend + node deps, copies .env.example to .env

2Choose an LLM provider#

Everything in .env has a local default that works with Docker Compose. Leave LLM_PROVIDER=fake to run without any API key: a deterministic fake model answers from your facts and is what the tests use. For real answers, add a Gemini key.

.env
LLM_PROVIDER=gemini_api
GEMINI_API_KEY=your-key-from-ai-studio
For local sign-in without Firebase, set AUTH_MODE=dev and NEXT_PUBLIC_DEV_MEMBER_EMAIL to the owner email in your seed.

3Start the stack#

bash
make dev   # docker compose up: postgres, redis, rustfs, firebase emulator, backend, frontend, widget demo
ServiceURL
Backend API + docshttp://localhost:8000/docs
Inbox / adminhttp://localhost:3000
Widget demo sitehttp://localhost:4000
RustFS console (S3 store)http://localhost:9001
Firebase Auth emulator UIhttp://localhost:4401

Migrations run automatically when the backend starts.

4Load the example seed#

bash
make seed   # loads the example org, its first owner, a project and its knowledge base

A seed folder holds org.json (the organization, members and projects) plus kb/company.json and kb/<project-slug>.json. Loading is idempotent: rows are matched by slug or email and updated, never duplicated. The first owner in the seed is how the first person gets access, since sign-in is invite-only.

5Try it#

  • Open the widget demo at localhost:4000 and ask a question.
  • Open the panel at localhost:3000, go to Inbox, and watch the conversation arrive live.
  • Ask the widget for a person, then Assign to me in the inbox and reply.

Other targets: make test, make lint, make migrate, make logs.

Result

The API, inbox and admin panel, widget demo site, object storage and auth emulator all run on your machine.

Next: Create a project and embed the widget