MangoStudio

AI-powered image generation and chat studio supporting Gemini, OpenAI-compatible, Anthropic, DeepSeek, and ChatGPT models.

Extend the agent without touching the codebase:

• Agent Skills — drop reusable instruction packs (plus bundled files and scripts) into a skills directory; MangoStudio advertises them to the model and loads each one on demand. See docs/reference/skills.md.
• MCP servers — connect Model Context Protocol servers over stdio or HTTP and expose their tools to the agent, namespaced per server and scoped by per-agent allowlists. See docs/reference/mcp.md.

🇧🇷 Leia em Português

Install

Run MangoStudio without cloning the repository. Every channel ships the same
prebuilt binary and verifies downloads
against SHA256SUMS where applicable.

The prebuilt app needs no local Rust compiler. cargo install mangostudio compiles the launcher
and requires Rust 1.99.0 or newer. cargo binstall uses a prebuilt archive when available; its
compilation fallback has the same Rust requirement. See the
Rust support and release policy when
upgrading from Rust 1.96 or 1.97.

Quick start with the shell installer:

curl -fsSL https://github.com/juliopolycarpo/mangostudio/releases/latest/download/install.sh | bash
mangostudio setup           # secret, service, start, and open a browser

On a bare Alpine (musl) system, run apk add bash curl libstdc++ first: the installer is a
bash script, and the hub links libstdc++ dynamically. Without it the installer's version
check fails with the loader's message and this same hint.

setup is the one command a fresh install needs: it generates an auth secret if
none exists, asks whether to keep the hub running across logout, starts it (or
reuses one already running), and opens it. Over SSH it prints the address and a
port-forward line instead of pretending to open a window. mangostudio serve
and mangostudio service install remain the direct equivalents.

The first time you sign in, the browser opens a short setup flow — folder,
toolchain, who answers, and one real question in your own project. Every step is
skippable and re-runnable from Settings → General. See
docs/guides/first-run.md.

On Windows, run the PowerShell installer:

irm https://github.com/juliopolycarpo/mangostudio/releases/latest/download/install.ps1 | iex

or use Scoop (see table above). The Cargo channel installs a
small launcher that downloads the same
checksum-verified archive on first run.

Both install scripts live in this repository (scripts/install/), ship as
release assets beside the archives they install, and are listed in SHA256SUMS;
the copies at https://mangostudio.dev/install.sh and install.ps1 mirror them.
Pass --canary (-Canary) for the newest canary pre-release or --version x.y.z
(-Version) to pin one.

Upgrade

mangostudio upgrade (alias update) works out how the binary was installed
and either upgrades in place or hands the job to the tool that owns it:

The hub checks for a newer release once a day; mangostudio status,
mangostudio doctor and the "This machine" page say when one exists, and the
page can apply it from the hub's own machine. [updates] check = false in
config.toml, MANGO_UPDATES_CHECK=false, NO_UPDATE_NOTIFIER, DO_NOT_TRACK
or CI turn the check off.

mangostudio is a single-binary CLI that manages one local server:

mangostudio serve [host|port|host:port] # foreground (default localhost:3001)
mangostudio serve lan:3001 -d           # background (logs to ~/.mango/logs/)
mangostudio service install # keep it running across logout and reboot
mangostudio status         # show the running instance
mangostudio restart        # restart it the way it was started
mangostudio logs -f        # follow the server log
mangostudio stop           # graceful shutdown
mangostudio doctor         # environment diagnostics

Run mangostudio with no arguments for the full command list. See
docs/reference/cli.md for details.

On first run, mangostudio serve can generate a strong BETTER_AUTH_SECRET and store it in ~/.mango/.env or ~/.mango/config.toml.
Set provider keys such as GEMINI_API_KEY when you are ready to use hosted models. Optional runtime settings include API_HOST, API_PORT, and DATABASE_PATH.
See mangostudio for the full environment.
For container deployment details, see docs/operations/deployment.md.

Prerequisites (development)

• Bun 1.4.3 or newer (bun upgrade, or
  curl -fsSL https://bun.sh/install | bash for a first install)
• Rust 1.99.0 or newer via rustup (curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh). The hub launches
  Local as the cargo-built mangostudio-runtime, and rust-toolchain.toml pins the version
  rustup installs on first build.
• One or more API keys or sign-in capable accounts for supported providers
  (Gemini, OpenAI-compatible, Anthropic, DeepSeek, ChatGPT)

Develop from source

1. Clone the repository:

   git clone <repo-url>
   cd mangostudio
   

2. Install dependencies:

   bun install
   

3. Start the development servers:

   bun run dev
   

   This first runs cargo build -p mangostudio-runtime --locked — the Local runtime the hub spawns —
   then starts one server at http://localhost:3001 (Elysia + Kysely/SQLite) that also
   builds and serves the React frontend. There is no separate frontend port. Without cargo it
   stops and prints the rustup one-liner; set MANGOSTUDIO_RUNTIME_BINARY to use a binary you
   already built instead.

Connector Configuration (Secrets)

MangoStudio has a flexible multi-connector system for managing multiple API keys with different persistence levels.

Supported Persistence Methods

1. OS Secret Store — Native secure storage via Bun.secrets. Recommended for maximum security.
2. config.toml — Stores keys in ~/.mango/config.toml. Ideal for sharing keys across instances or CLI tools.
3. .env file — Adds variables to the ~/.mango/.env file.

How to Configure

Go to the Settings page in the MangoStudio interface to add and manage connectors.

For each connector, you can enable or disable specific models (e.g., Gemini 2.5 Flash, Gemini 2.0 Flash Image). MangoStudio automatically selects the correct connector based on the active model in the chat.

Supported Providers

Terminal Sync

You can manually add keys to ~/.mango/config.toml:

[gemini_api_keys]
personal = "your-key-here"
work = "another-key-here"

MangoStudio will sync these keys automatically the next time the Settings page is loaded or a generation is requested.

Cursor

Cursor is not a connector. It runs as an external agent — pick it in the composer's runner
selector and it uses your own Cursor CLI login, rules and MCP configuration. The
MangoStudio-owned Cursor provider is deprecated; existing connectors stay editable but no longer
run turns. See docs/providers/cursor.md.

ChatGPT Subscription Connector

The ChatGPT provider uses browser sign-in instead of an API key. It starts a
temporary callback server on port 1455, stores rotating OAuth tokens in the OS
secret store, and uses the models available to the signed-in ChatGPT plan. See
docs/providers/chatgpt.md for details and remote-host
port-forwarding notes.

Project Structure

mangostudio/
├── .mango/            # Example configuration templates only
│   └── config.toml.example
├── apps/
│   ├── api/
│   │   └── src/
│   │       ├── lib/                # Config, runtime paths, SPA guard
│   │       ├── modules/            # Domain modules (DDD-inspired)
│   │       │   ├── chats/          # application/ domain/ http/ infrastructure/
│   │       │   ├── messages/       # application/ domain/ http/ infrastructure/
│   │       │   ├── generation/     # application/ domain/ http/ infrastructure/
│   │       │   ├── connectors/     # application/ domain/ http/ infrastructure/
│   │       │   ├── app-settings/   # application/ http/ infrastructure/
│   │       │   ├── provider-settings/  # application/ http/ infrastructure/
│   │       │   ├── tool-settings/  # application/ http/ infrastructure/
│   │       │   ├── prompt-rules/   # application/ http/
│   │       │   └── attachments/    # application/ infrastructure/
│   │       ├── plugins/            # Auth guard, rate limiting, error handler
│   │       ├── services/           # AI providers, tools, secrets, generated images
│   │       │   ├── providers/      # Multi-provider implementations + core infrastructure
│   │       │   ├── tools/          # Tool registry + built-in tools
│   │       │   └── generated-images/  # Generated image file storage
│   │       └── db/                 # Kysely + SQLite + migrations
│   ├── frontend/
│   │   └── src/
│   │       ├── components/
│   │       │   └── ui/             # Design system (Button, Input, Card, Spinner, Toast, Toggle)
│   │       ├── features/           # Feature modules (chat, gallery, generation, settings, sidebar)
│   │       ├── hooks/              # React hooks (use-i18n, use-app-state, use-model-catalog…)
│   │       └── routes/             # TanStack Router pages
│   └── shared/
│       └── src/
│           ├── contracts/          # Contract barrel export
│           ├── <module>/           # Per-module contracts + schemas (auth, chat, connectors…)
│           ├── streaming/          # SSE event types + schemas
│           ├── types/              # Domain types (provider, agent-events, gallery)
│           ├── i18n/               # pt-BR / en dictionaries + types
│           └── test-utils/         # Shared mock factories
├── docs/
│   ├── README.md                   # Docs hub and reading paths
│   ├── architecture/              # System design and cross-cutting runtime flows
│   ├── features/                  # Product-area implementation docs
│   ├── providers/                 # Provider guides and provider-specific notes
│   ├── reference/                 # API, testing, and feature maps
│   ├── guides/                    # Contributor task-oriented guides
│   ├── operations/                # Deployment and security
│   └── pt-br/                     # Curated Portuguese translations
├── package.json                    # Bun workspace root
└── tsconfig.json                   # Base TypeScript configuration

Main Scripts

Development Tooling

These binaries are installed as devDependencies and invoked through the root bun run scripts. No global installation is required.

Local Validation

Git Hooks

A lefthook pre-commit hook is installed automatically via bun install (through the prepare script). It runs the following checks in parallel on every git commit:

Files that pass formatting are re-staged automatically. All hooks must succeed for the commit to proceed.

Manual Checks

• bun run check — full check (Biome, dprint, typecheck, circular deps, and Knip).
• bun run check --staged — only the workspaces touched by staged files (used by the pre-commit hook).
• bun run check --changed — only the workspaces changed vs origin/main.
• bun run fix --staged — auto-fix only the affected workspaces.

Architecture

Editor Setup

Claude Code hooks auto-prepend node_modules/.bin to PATH on session start and directory changes (SessionStart / CwdChanged). After every write or edit, a PostToolUse hook runs auto-fix.mjs to format the touched file.

OpenCode

OpenCode reads formatter wiring from opencode.json.

Prettier is disabled.

Code Quality

Biome (Lint)

Configured in biome.json with recommended rules enabled and workspace-specific overrides.

Global rules (all files):

TypeScript/TSX overrides (**/*.{ts,tsx}):

Frontend-specific overrides (apps/frontend/**/*.{ts,tsx}):

Per-workspace relaxations:

Additional formatting and assist settings:

• Line width: 100, indent: 2 spaces, single quotes, semicolons, trailing commas (es5)
• CSS parser enables Tailwind directives
• HTML formatter self-closes void elements
• assist.actions.source.organizeImports is enabled

dprint (Format)

Configured in dprint.json with the following scope and settings:

Circular Dependencies

Biome checks imports as part of bun run check, including value, type-only and self-import cycles. Each workspace scans TS, TSX, MTS, CTS, JS, JSX, MJS and CJS files, including top-level helpers, generated files and gitignored build output, through biome.cycles.json. JavaScript files are checked both as dependencies of TypeScript files and as independent roots. Only node_modules and .git are excluded from the cycle scan. Normal formatting and lint still follow biome.json.

Copy/Paste Detection

Scanned via jscpd during CI (qa-gate). Configuration is defined inline in scripts/qa-gate/collect.ts.

Design System

The frontend ships with a built-in design system under apps/frontend/src/components/ui/:

• Button — variants primary, secondary, ghost; loading prop
• Input — label, error message, spread of InputHTMLAttributes
• Card — variants glass (glassmorphism) and solid
• Spinner — loading indicator with sizes sm, md, lg
• Toast — non-blocking notifications via useToast() hook
• Toggle — accessibility-first toggle switch

Internationalization (i18n)

UI strings are centralized in @mangostudio/shared/i18n. Supports pt-BR (default) and en, with automatic detection via navigator.language.

import { useI18n } from '@/hooks/use-i18n';

function MyComponent() {
  const { t } = useI18n();
  return <h1>{t.auth.loginTitle}</h1>;
}

The Messages type is inferred directly from the pt-BR.ts dictionary (as const). Adding a key without translating it in en.ts is a compile-time error.

Documentation

• docs/README.md — docs hub, audiences, and reading order
• docs/guides/contributor-quickstart.md — fastest contributor onboarding path
• docs/architecture/continuation.md — continuation architecture deep-dive
• docs/providers/development.md — provider integration guide
• docs/reference/cli.md — CLI commands and install channels
• docs/reference/releasing.md — release runbook and distribution channels
• docs/reference/testing.md — testing strategy and harness rules
• docs/reference/agent-playbooks.md — feature-by-feature file maps
• .github/CONTRIBUTING.md — contribution guidelines

Standalone Build Notes

The bun run build --binary command compiles the API into platform-specific binaries under .mango/out/<platform>/, next to the cargo-built mangostudio-runtime. Locally it builds the host's own platform (--platform <host>); other platforms need prebuilt runtimes via --runtime-dir <dir> (see releasing).

• The database is persisted at ~/.mango/database.sqlite by default.
• Frontend assets are embedded into the executable at build time.

License

This project is licensed under the MIT License.