v0.2.57Managed setup, Apps, projects, and files
gugu
中文

Self-host gugu (Community Edition)

Use your own Supabase project as the backend and run the client from source.

Both the gugu client and the community backend are open source: the client is OpenDCAI/gugu on GitHub, and the backend is OpenDCAI/gugu-supabase. The backend runs on your own Supabase project, so accounts, messages, and files are all stored on your side. The Supabase Free plan is enough for a small team.

For step-by-step instructions, see the English guide docs/self-hosting.md in the backend repo. This page only covers the prerequisites and main steps.

What the Community Edition includes

  • Email verification-code sign-in, Contacts, and friend requests
  • Direct messages and group chats, with Agents you can add to groups and messages delivered in real time
  • Attachments, stored in your own Supabase Storage
  • Local Agent sessions, using your existing accounts for Claude Code, Codex, and similar tools on your own computer

What the Community Edition doesn't include

  • Official cloud hosting (cloud computers)
  • Official models, Membership, and payments
  • Remote tunnel relay (opening this machine's terminal or browser from another computer)
  • Multi-user collaborative file editing, unless you also deploy the file service in the backend repo

What to prepare

  1. A Supabase account, plus a new empty project just for gugu — don't mix it with other data.
  2. A Supabase personal access token. Generate it on your account's Access Tokens page, scoped to this project only. Keep the token on your own computer; don't send it to anyone or commit it to code.
  3. An SMTP email service, such as Resend, Brevo, or AWS SES. gugu signs you in with a 6-digit code sent by email. Supabase's built-in email can only send 2 emails per hour, and only to members of your organization, so you must use your own SMTP. The code itself comes from the email template, which the setup script updates; free projects cannot edit templates while they use the built-in email, so set up SMTP first. For setup steps, see docs/self-hosting-smtp.md in the backend repo.
  4. Git, Node 24, and pnpm 10.28.2 installed on your computer; on a Mac you also need the Xcode Command Line Tools.

Setup steps

  1. In the Supabase dashboard, turn on custom SMTP and enter the address and account your email service gives you.
  2. Download both repos and run pnpm run setup in the backend repo. It sets up the database, Edge Functions, storage, and real-time updates, and writes the connection details into the client directory. Note it is not pnpm setup — that is a different, built-in pnpm command.
  3. In the client repo, run pnpm install, then pnpm rebuild:native, and start it with `GUGU_DB_TARGET=local bash scripts/dev-app.sh`.
  4. Sign in with the code sent to your email, create a new session, pick an installed Agent, and you're ready to go.

Limits you'll hit on the Free plan

  • A project is paused after a week without use; just click restore in the Supabase dashboard.
  • 500 MB of database, 1 GB of file storage, and no single attachment over 25 MB.
  • 200 concurrent realtime connections.

If you run into problems, check docs/self-hosting-free-plan.md in the backend repo first; it lists common issues as "symptom → cause → what to do".