ahmadrosid/nakama

What It Is

Nakama is a self-hostable AI agent platform aimed at teams rather than a single operator. Users chat with agents from a ChatGPT-like dashboard, and each agent carries its own prompt files, tools, skills, memory and messaging channels. It is explicitly designed for multi-organization use: a single server supports many orgs with invites, roles and isolation between agents. The README names OpenClaw and Hermes Agent as comparable systems and positions Nakama as a team-oriented alternative. The system design is documented separately in ARCHITECTURE.md.

Agents can be connected to Telegram, WhatsApp, Discord and Slack, plus Composio for access to external apps. Configuration lives in a control center for AI providers, tools, skills, MCP, plugins and integrations. The first server run prompts for a provider and API key if none is set, then saves settings to ~/.nakama/config.ini.

Quick Start

The fastest path is the managed cloud service: create an account, provision an instance, and finish the in-browser setup wizard. This requires no Bun, Docker or VPS. See Nakama Cloud.

To run locally you need Bun. From the repository root:

bun install
bun run dev:web

This starts the web app and the server if needed; open http://localhost:3003. To run the server alone, use bun run dev:server. The dashboard is the entry point for creating agents and enabling integrations.

Alternatively, run a single Docker container for local trials:

docker pull ghcr.io/ahmadrosid/nakama:latest
umask 077
printf 'NAKAMA_SECRETS_KEY=%s\n' "$(openssl rand -base64 32)" > nakama-secrets.env
docker run -d -p 4310:4310 -v nakama-data:/nakama/data --env-file nakama-secrets.env --name nakama ghcr.io/ahmadrosid/nakama:latest

Open http://localhost:4310. The server listens on http://127.0.0.1:4310 by default, and interactive API docs are served at http://127.0.0.1:4310/docs.

Deployment Notes

For server use the README recommends Compose rather than a bare container: it pins the version, keeps a daily encrypted backup and can expose an Update button. Set NAKAMA_VERSION to the latest release and put an HTTPS proxy in front; see Deployment hardening. A plain container needs roughly 200 MB idle, enough for 1 vCPU and 1 GB when the server runs alone; check Requirements before enabling channel workers.

The reset script ./scripts/docker-destroy.sh removes data and every container publishing port 4310, including unrelated ones. Review the reset documentation before using it. Windows has no published installation link yet; unsigned MSIX files in older releases are Partner Center uploads, not installable downloads, and availability is described in the desktop README. macOS desktop builds are available from desktop releases.

Constraints

Local development requires Bun; Docker deployment needs Docker and Compose for the recommended server setup. Team features (orgs, invites, roles, agent isolation) assume a server deployment rather than a single desktop user. Channel integrations depend on the corresponding provider credentials, and Composio connects to external apps through its service. The project is MIT licensed.

HotRepo's take

Nakama was recorded on the TypeScript weekly list for the week of 2026-11-04 at position 14, with 773 stars and 129 forks and a gain of 109 stars in that window. That is a single weekly language-list observation, so it supports saying the project drew attention during that week, not that it is trending steadily. The notable angle is its team framing: multi-org isolation, roles and shared agent configuration make it an attempt at a company-level agent workspace rather than a personal chat client.