brightbeanxyz/brightbean-studio: Self-Hosted Social Media Management

brightbeanxyz/brightbean-studio: Self-Hosted Social Media^{↗ Bright Coding Blog} Management

Managing multiple social media accounts across platforms shouldn't require paying $100–300 per month to a SaaS vendor that gates features behind tiered pricing. For agencies, creators, and small teams who need to schedule content, coordinate approvals, and track performance across Facebook, Instagram, LinkedIn, TikTok, and more, the economics of commercial tools scale poorly. brightbeanxyz/brightbean-studio offers a different path: an open-source, self-hostable platform built on Django that delivers core social media management capabilities without per-seat, per-channel, or per-workspace limits. With 2,037 GitHub stars, 403 forks, and active development through mid-2026, it represents a mature alternative for teams ready to own their infrastructure.

What is brightbeanxyz/brightbean-studio?

brightbeanxyz/brightbean-studio is an open-source social media management platform licensed under GNU Affero General Public License v3.0. Built primarily in Python^{↗ Bright Coding Blog} on Django 5.x, it targets creators, marketing agencies, and small-to-medium businesses who manage multiple client accounts or brand presences across social platforms.

The project's architecture reflects a deliberate choice toward simplicity and self-ownership. Rather than routing through aggregator services that introduce vendor lock-in, all platform integrations communicate directly with official first-party APIs using the user's own developer credentials. This design eliminates middleman dependencies and ensures data flows directly between the user and each social platform.

The codebase is actively maintained, with the last commit dated July 12, 2026. A free hosted version runs at brightbean.xyz/studio for users who want immediate access without deployment overhead. For those prioritizing data sovereignty or customization, self-hosting options span Heroku, Render, Railway, VPS with Docker, or local development environments.

The technical stack is intentionally conservative: Django templates with HTMX and Alpine.js on the frontend, Tailwind CSS^{↗ Bright Coding Blog} for styling, PostgreSQL^{↗ Bright Coding Blog} for production data, and django-background-tasks (without Redis requirement) for job processing. This stack prioritizes operational simplicity over architectural complexity—a meaningful consideration for teams without dedicated DevOps^{↗ Bright Coding Blog} resources.

Key Features

Multi-workspace architecture with granular access control. The platform supports unlimited organizational hierarchies: organizations contain workspaces, which contain members with role-based access control. Custom roles can be defined beyond default permissions, and a dedicated "Client" role enables external collaborators to participate without full system access.

Content composition and workflow management. The composer supports per-platform caption and media overrides, allowing a single post concept to be adapted for Instagram's visual format versus LinkedIn's professional tone. Version history, reusable templates, content categorization, and a Kanban idea board provide structure for content planning.

Scheduling with intelligent queue management. The visual calendar interface supports recurring weekly posting slots per account and named queues that auto-assign posts to the next available time slot—reducing manual scheduling overhead for high-volume operations.

Direct API publishing with resilience. The publishing engine handles automatic retries and maintains per-account rate-limit tracking, with a 90-day publish audit log for compliance and debugging. Direct first-party API integration means no aggregator fees or service degradation from third-party intermediaries.

Unified social inbox with sentiment analysis. Comments, mentions, direct messages, and reviews from connected platforms aggregate into a single interface. Features include assignment routing, threaded replies, historical backfill capability, and automated sentiment classification.

Analytics from native APIs. Rather than synthetic metrics, the platform queries each platform's native API for per-post and channel-level performance data. KPI cards, trend charts (7/30/90-day windows), and sortable data tables cover views, engagement, follower growth, reach, and watch time where available.

Client portal with passwordless access. External stakeholders receive 30-day magic links for approval or rejection actions, eliminating account creation friction while maintaining audit trails.

Use Cases

Marketing agency managing 15+ client accounts. An agency can provision separate workspaces per client under a single organization, apply distinct branding per workspace, and use the Client role to loop stakeholders into approval workflows without exposing other clients' data. The unlimited workspace model eliminates the per-client surcharges common in commercial tools.

Solo creator cross-posting to 8+ platforms. A content creator producing video for YouTube, TikTok, and Instagram while maintaining text presence on LinkedIn, Bluesky, Threads, and Mastodon can compose once with per-platform adaptations, schedule across all channels, and monitor engagement from a single dashboard rather than logging into each platform individually.

Small business with compliance requirements. The self-hosted deployment option keeps social media credentials and published content within the organization's infrastructure. Encrypted token storage, audit logs, and the absence of third-party data processors support GDPR and industry-specific compliance frameworks more readily than multi-tenant SaaS alternatives.

Development team building social features into a product. The REST API and MCP (Model Context Protocol) server enable programmatic access for automation scripts, AI agents, or integration with existing content pipelines. Workspace-scoped API keys with granular permissions support secure machine-to-machine workflows.

Non-profit with volunteer coordinators. The approval workflow system (configurable as none, optional, internal, or internal-plus-client) lets volunteer content creators draft posts while designated approvers maintain editorial control. The Kanban idea board captures concepts from brainstorming sessions without immediate scheduling commitment.

Installation & Setup

The quickest production path uses Docker Compose. The README provides exact commands:

git clone https://github.com/brightbeanxyz/brightbean-studio.git
cd brightbean-studio
cp .env.example .env

Edit .env to point DATABASE_URL to the Docker service name:

DATABASE_URL=postgres://postgres:postgres@postgres:5432/brightbean

Start all services:

docker compose up -d --build
docker compose exec app python manage.py createsuperuser

The migrate Compose service runs database migrations automatically before the app and worker services start. The tailwind service compiles CSS; first build takes 60–90 seconds for npm install, with subsequent starts being instant. Monitor with docker compose logs -f tailwind.

For local development without Docker or PostgreSQL, the project supports SQLite:

git clone https://github.com/brightbeanxyz/brightbean-studio.git
cd brightbean-studio
cp .env.example .env

Replace DATABASE_URL in .env:

DATABASE_URL=sqlite:///db.sqlite3

Set up Python dependencies:

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Install frontend build tools:

cd theme/static_src
npm install
cd ../..

Run migrations and create admin:

python manage.py migrate
python manage.py createsuperuser

Development requires three terminal processes: Tailwind watcher (cd theme/static_src && npm run start), Django dev server (python manage.py runserver), and background worker (python manage.py process_tasks).

Real Code Examples

The README includes a management command for historical message backfill:

python manage.py backfill_inbox --days 7

This command imports historical messages from connected platforms. The --days 7 parameter specifies the lookback window; optional flags include --platform NAME for single-platform backfill and --account-id UUID for specific accounts. This is particularly useful when onboarding new client accounts where existing conversations need context for response continuity.

For API access, the README documents Bearer token authentication:

Authorization: Bearer bb_studio_...

API keys are issued from Organization → API Keys, scoped to workspaces with optional account allowlisting. The key inherits a subset of the issuer's permissions; revocation is immediate. This design supports automation scripts and third-party integrations without exposing full user credentials.

The MCP server connection for Claude Code uses:

claude mcp add --transport http brightbean {APP_URL}/api/v1/mcp \
  --header "Authorization: Bearer bb_studio_..."

This enables AI agents to interact with the platform through standardized JSON-RPC 2.0 over HTTP, with the same permission model as REST clients.

Advanced Usage & Best Practices

Storage backend selection for ephemeral platforms. Heroku, Render, and Railway use ephemeral filesystems—uploaded media persists only until the next redeploy. Set STORAGE_BACKEND=s3 with S3-compatible object storage (AWS S3, Cloudflare R2, MinIO) for production deployments on these platforms. The .env.example documents all required S3 variables.

LinkedIn credential strategy. The platform supports two LinkedIn integration paths: Path A (Personal, any developer can obtain) with ~60-day token lifespans and no refresh capability, or Path B (Company Page verified, requires LinkedIn review) with 365-day refresh tokens and inbox access. If using Path B exclusively, the system automatically reuses those credentials for personal connections—simplifying configuration while gaining full functionality.

Worker process monitoring. Posts failing to publish typically indicate the background worker isn't running. Verify with docker compose logs worker or python manage.py process_tasks in local environments. The django-background-tasks implementation avoids Redis dependency but requires explicit worker process management.

OAuth redirect URI exactness. Platform OAuth errors almost always trace to redirect URI mismatches. The required format is {APP_URL}/social-accounts/callback/{platform}/ with trailing slash. TikTok specifically requires social1 as the platform slug—TikTok's brand protection rejects URIs containing "tiktok".

Comparison with Alternatives

The trade-off is clear: commercial tools offer zero-setup onboarding and customer support, while brightbeanxyz/brightbean-studio provides cost elimination, data sovereignty, and customization potential at the expense of operational responsibility. For teams with existing infrastructure management capability or strict data residency requirements, the self-hosted model is advantageous. For users prioritizing convenience over control, the free hosted version narrows the gap.

FAQ

Is brightbeanxyz/brightbean-studio actually free? Yes. The AGPL-3.0 license permits self-hosting without fees. A free hosted version exists at brightbean.xyz/studio.

What Python version is required? Python 3.12 or newer, per the project badges and setup documentation.

Can I use SQLite in production? The README notes SQLite is "fine for local development and small deployments" but recommends PostgreSQL for production or heavy concurrent usage.

Does it support two-factor authentication? TOTP-based 2FA is documented as on the roadmap, not currently implemented.

How do I update a self-hosted instance? git pull followed by docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build for Docker deployments.

What happens if the background worker stops? Scheduled posts queue but don't publish until the worker restarts. Monitor worker process health as part of deployment operations.

Can I restrict API keys to specific social accounts? Yes. API keys can be allowlisted to specific accounts within their workspace scope.

Conclusion

brightbeanxyz/brightbean-studio occupies a specific niche: teams who need multi-platform social media management, reject recurring SaaS costs that scale with account growth, and possess (or can acquire) basic infrastructure management skills. The Django-based architecture prioritizes operational clarity over bleeding-edge complexity, making it approachable for Python-experienced teams.

The platform is best suited for marketing agencies with multiple clients, creators managing distributed personal brands, and organizations with data residency requirements. The free hosted version lowers the barrier for evaluation, while self-hosting options provide a migration path to full control.

The 2,037-star repository shows sustained community interest, and the July 2026 commit activity indicates active maintenance. For teams currently paying premium prices for social media management and wondering whether the functionality justifies the cost, brightbeanxyz/brightbean-studio offers a credible, inspectable alternative.

Explore the repository, review the deployment options, and determine whether your team's scale and technical capacity align with the self-hosted model. The code is available at https://github.com/brightbeanxyz/brightbean-studio.