Initiative
Pre-release software — this project hasn't reached v1.0.0 yet. The API may change between minor releases.
What is Initiative?
Initiative is a shared workspace for organizing the things a group needs to get done. Projects, tasks, documents, calendars, and other tools all live together, so you don't have to stitch your work across a dozen different apps.
It's designed for small businesses, clubs, committees, event teams, families, and other groups that need to coordinate work without becoming project-management experts.
Start with a board and a few tasks. As your needs grow, add the tools you need — and leave everything else out of the way.
Initiative also gives you fine-grained control over who can see and change your work, and a marketplace lets you add ready-made apps and dashboards built by other groups.
It's project management that starts simple and grows with you.
Roadmap
Where we are
Initiative is already a full-featured workspace for groups:
- Tasks & projects with Kanban, Table, Calendar, and other views
- Collaborative documents including rich text, spreadsheets, and whiteboards with real-time editing
- Calendars, bulletin boards, queues, counters, dashboards, and more
- A curated marketplace of ready-made apps and dashboards
- Notifications and BYOK AI integration
- Self-hosting with Docker and support for multiple guilds
What's next
🧩 More apps, more possibilities We're continuing to build the marketplace and the ecosystem around it — more dashboards, more useful apps, and better ways for groups to build and share their own.
🌎 A more connected community Initiative is becoming more than a place for private work. We're adding public content, user profiles, and community features that make it possible to discover what other people and groups are building.
✨ Polish everything Accessibility, UX improvements, performance, testing, and the countless little things that make Initiative nicer to use.
🔌 Connect to the rest of your world Better APIs, integrations, templates, and apps that securely connect Initiative to the tools your group already uses.
Where we're headed
Initiative is bootstrapped by two people, and we're building it for the long haul — not toward an acquisition, IPO, or enterprise sales machine.
Initiative is open core. The application — everything you self-host — stays open source under the AGPL. Apps can be built and distributed independently, whether they're hosted inside Initiative or run as separate services. See License for what's open and what isn't.
We're also building Initiative Cloud for groups who don't want to manage their own infrastructure, with paid features like hosted apps, automations, and other conveniences that make Initiative easier to run.
Build something useful. Share it. Find something someone else built. Make Initiative your own.
Quick Start
Docker Compose (Recommended)
# 1. Download the example compose file
curl -O https://raw.githubusercontent.com/Morelitea/initiative/main/docker-compose.example.yml
cp docker-compose.example.yml docker-compose.yml
2. Edit configuration — set a secure SECRET_KEY at minimum
nano docker-compose.yml
3. Start the application
docker-compose up -d
4. Access Initiative at http://localhost:8173
What's included:
- PostgreSQL 17 with persistent storage and Row Level Security
- Automatic database role creation and migrations
- React frontend served via FastAPI
- Health checks and automatic restarts
- The first user to register becomes the platform owner
- Configure SMTP under Settings → Platform → Email to enable email notifications
- Create your first guild and start inviting people
[!CAUTION]
Do not usedevimages for production or customer deployments.devcontains experimental work that may not make it into a stable release. Uselatestor a tagged release frommain.
Docker Hub Images
docker pull morelitea/initiative:latest # latest release
docker pull morelitea/initiative:0.71 # specific minorImages support linux/amd64 and linux/arm64 architectures.
Apps
Initiative is a PWA — open it over HTTPS and install it from the browser (address-bar install icon on desktop Chrome/Edge, Add tab to taskbar in Firefox on Windows, Add to Home Screen on iOS Safari, Install app on Android Chrome). It gets its own window, stays signed in, and serves recently viewed projects and tasks offline.
Android also has a native Capacitor app, which adds push notifications. It pulls each new web bundle from your server over the air, so you only reinstall when the native shell changes.
Or take the newest release with an .apk attached — the app is only rebuilt when the native shell changes, so most releases carry none. Full instructions: Installing the app.
Configuration
Key Environment Variables
| Variable | Description | Default |
|---|---|---|
| DATABASE_URL | PostgreSQL connection as the database owner (see Database connection) | Required |
| SECRET_KEY | JWT signing and encryption key | Required |
| APP_URL | Public base URL (required for OIDC callbacks) | - |
| DISABLE_GUILD_CREATION | Restrict guild creation to guilds.manage holders (operator and owner) | false |
| ENABLE_PUBLIC_REGISTRATION | Allow registration without invite link | true |
| ENABLE_MCP | Mount the in-app MCP server at /api/v1/mcp/ for AI assistants (see MCP Server) | false |
| MARKETPLACE_EXTRA_CATALOG_DIR | Directory of your own marketplace listing files (see Publishing your own listings) | - |
| CAPTCHA_PROVIDER / CAPTCHA_SITE_KEY / CAPTCHA_SECRET_KEY | Captcha on registration and emailed sign-in codes (hcaptcha, turnstile, or recaptcha v2). First boot only; then Settings → Platform → Security | - |
| BEHIND_PROXY | Trust X-Forwarded-For headers | false |
| FORWARDED_ALLOW_IPS | Trusted proxy IPs (when BEHIND_PROXY=true) | * |
| FIRST_OWNER_EMAIL | Bootstrap owner email (legacy FIRST_SUPERUSER_EMAIL accepted) | - |
| FIRST_OWNER_PASSWORD | Bootstrap owner password (legacy FIRST_SUPERUSER_PASSWORD accepted) | - |
| SMTP_HOST / SMTP_PORT / SMTP_USERNAME / SMTP_PASSWORD | SMTP server configuration. First boot only; then Settings → Platform → Email | - |
| SMTP_FROM_ADDRESS | Email sender address. First boot only | - |
| FCM_ENABLED (+ FCM_*) | Firebase Cloud Messaging for mobile push. First boot only; then Settings → Platform → Push notifications | false |
| PUID | UID the container runs as (for rootless/NAS setups) | 1000 |
| PGID | GID the container runs as (for rootless/NAS setups) | 1000 |
For FCM setup, see docs/en/running-a-server/push-notifications.md. For a complete list of options, see backend/.env.example.
Database connection
Set DATABASE_URL to the database, connecting as its owner. At startup the app uses it to create three least-privilege logins, hand them the schema and install the guild-search match operator, then closes it and serves everything on those logins:
app_provisionerruns migrations and creates/removes guild schemas. Deliberately not a superuser.app_useris the role every request runs on.app_adminis the system role for background jobs and startup seeding.
SECRET_KEY and re-applied on every start, so rotating SECRET_KEY rotates them too. The example compose file points DATABASE_URL at the POSTGRES_USER it creates, so docker compose up works as-is.
Naming the logins yourself (a pooler with its own user list, managed Postgres, a DBA): set DATABASE_URL to app_provisioner and add DATABASE_URL_APP (app_user) and DATABASE_URL_ADMIN (app_admin). Add DATABASE_URL_BOOTSTRAP as the owner and the app creates those logins with the passwords in their URLs; leave it out and the app only checks they exist. python -m app.db.bootstrap --print-sql prints exactly what to apply by hand.
Running as a non-root user (PUID/PGID)
The container starts as root so its entrypoint can create the runtime user, fix ownership on the uploads volume, and then drop privileges with gosu. The main uvicorn process runs unprivileged — by default UID/GID 1000:1000 with no Linux capabilities.
To run as a different UID/GID (for example, to match the NAS user that owns the uploads volume), set the PUID/PGID environment variables. Do not add a Docker user: (Compose) or --user (run) override — that starts the entrypoint as non-root, so it can't create the user and fails with fatal: Only root may add a user or group to the system. PUID/PGID is the supported knob; 0 (root) is rejected.
MCP Server
Initiative ships an optional, in-app MCP server so MCP-compatible AI assistants (such as Claude Code) can work with your data on your behalf. It is route-backed: every tool call runs through the real API with your authentication and the same Row-Level-Security access rules as the app, so a tool can only ever reach data you can reach — scoped per guild and initiative. It is off by default.
Enable it
Set ENABLE_MCP=true (in .env or your container environment) and restart — the endpoint is mounted at startup:
ENABLE_MCP=trueThe server is then served at /api/v1/mcp/ (note the trailing slash) on your deployment's public host — i.e. APP_URL you set in .env. (For local testing that's http://localhost:8173/api/v1/mcp/; localhost is for testing only, not your launched URL.) Because it is in-app, it ships in the Docker image — flipping the env var is all a deployer needs. Leave it off where you don't want the surface; it is gated at the infra level, not by a UI toggle.
Connect a client (Claude Code example)
- Mint a personal API key in Settings → Security. Tick Read-only for read access only (recommended for most uses); pin it to a single guild to limit its blast radius. A full-access key is required only if you want the write tools.
- Register the server:
claude mcp add --transport http initiative \
https://your-host/api/v1/mcp/ \
--header "Authorization: Bearer ppk_your_key_here"- Use it — ask your assistant things like "list my projects in Initiative" or "add a task to the Auth project." Write actions are confirmed by the client before they run.
What it can access
The surface is curated and default-deny — only the following are exposed. Everything else (tags, properties, membership and roles, operator endpoints, auth, settings, uploads and downloads, deletes, archiving, bulk operations, sharing/grants, and AI generation) is not.
Reads (any API key) — initiatives and every tool they hold:
| Tool | Endpoint |
|---|---|
| List / read initiatives (+ members, roles, your permissions) | GET /c/{guild}/initiatives… |
| List / read projects (+ activity, favorites, task statuses) | GET /c/{guild}/projects… |
| List / read tasks | GET /c/{guild}/tasks… |
| List / read documents (+ versions, backlinks) | GET /c/{guild}/documents… |
| List / read queues and their items | GET /c/{guild}/queues… |
| List / read counter groups and counters | GET /c/{guild}/counter-groups… |
| List / read calendars and their events | GET /c/{guild}/calendars…, GET /c/{guild}/calendar-events… |
| List / read notices | GET /c/{guild}/posts… |
| List / read dashboards, and what a tile currently shows | GET /c/{guild}/dashboards… |
| Read a comment thread, or one comment | GET /c/{guild}/comments… |
| Your projects / tasks / documents / calendars across all guilds | GET /me/projects, GET /me/tasks, … |
Writes (full-access key only — a read-only key is rejected with 403; each is confirmed in the client) — create and edit each of the same things:
| Tool | Endpoint |
|---|---|
| Create / edit a project | POST /c/{guild}/projects/, PATCH …/projects/{id} |
| Create / edit / move a task | POST /c/{guild}/tasks/, PATCH …/tasks/{id}, POST …/tasks/{id}/move |
| Create / edit a document | POST /c/{guild}/documents/, PATCH …/documents/{id} |
| Create / edit a queue, and its items | POST /c/{guild}/queues/, PATCH …/queues/{id}, POST …/queues/{id}/items, PATCH …/items/{id} |
| Create / edit a counter group, and its counters | POST /c/{guild}/counter-groups/, PATCH …/{id}, POST …/counters, PATCH …/counters/{id} |
| Move a counter's count | POST …/counters/{id}/set, /increment, /decrement |
| Create / edit a calendar, and its events | POST /c/{guild}/calendars/, PATCH …/{id}, POST /c/{guild}/calendar-events/, PATCH …/{id} |
| Create / edit a notice | POST /c/{guild}/posts/, PATCH …/posts/{id} |
| Create / edit a dashboard | POST /c/{guild}/dashboards/, PATCH …/dashboards/{id} |
| Add / edit a comment | POST /c/{guild}/comments/, PATCH …/comments/{id} |
Security notes
- Least privilege: prefer a read-only, single-guild API key. A read-only key cannot invoke the write tools.
- No ambient access: the tools carry no standing privilege — each call authenticates as the key's user and is scoped by RLS, exactly like a normal request.
- Revocable: delete the key in Settings → Security at any time; a password reset also revokes it.
Technology Stack
| Layer | Technologies | |---|---| | Backend | FastAPI, SQLModel + SQLAlchemy, PostgreSQL 17, Alembic, asyncpg | | Frontend | React 19, TypeScript, Vite, React Query, Tailwind CSS, shadcn/ui, dnd-kit | | Mobile | Capacitor (iOS and Android), Firebase push notifications | | Infrastructure | Docker, GitHub Actions (multi-arch builds), Dependabot |
Contributing
See CONTRIBUTING.md for details. PRs must target the dev branch.
By contributing, you agree to the terms of the Contributor License Agreement.
Quick start: Open the project in VS Code and run Tasks: Run Task > dev:setup from the Command Palette. This starts Postgres, runs migrations, seeds test data, and launches both servers. Login with [email protected] / changeme.
Security
See SECURITY.md for our security philosophy and how to report vulnerabilities.
License
Initiative is open core.
The application in this repository is open source under the GNU Affero General Public License v3.0 (AGPL-3.0) — the whole product, with nothing held back for a paid edition. Copyright is retained by the project maintainers, who reserve all commercial rights.
What's open:
| Repository | License | What it is | |---|---|---| | Morelitea/initiative | AGPL-3.0 | The application: backend, frontend, and mobile builds | | initiative-app-kit | MIT | The protocol half of writing an app for Initiative | | initiative-github | MIT | The reference app — clone it to start your own |
What isn't: automations and billing are proprietary, are not published, and are not part of this repository. They exist to run Initiative Cloud; a self-hosted install is the complete product without them.