Genfeed

Genfeed.ai

The open-source content engine your agent can run. Self-host it free or use Cloud.

Create on-brand videos, images and posts, then review and publish to your connected channels. Work in Genfeed or connect the AI agent you already use.

If Genfeed is useful, star it on GitHub ⭐ so others can find it.

One real generation on a self-hosted instance: prompt, generate, approve. About 20 seconds, unedited apart from trimming.

npx @genfeedai/create my-genfeed

Needs Docker Compose v2 and Node.js 24. The wizard verifies the release bundle, asks for your OpenRouter API key, then starts it. Install guide: genfeed.ai/self-hosted · docs.genfeed.ai.

Warning

Genfeed is 0.x and under active development. Breaking changes ship with an Upgrade note in the release body; semver becomes strict at v1.0.0.

Self-host it (Community), run it on your Mac (Desktop), or use the hosted product at genfeed.ai (SaaS). Same code, three deployment modes.

Requirements (Community)

• Docker Engine with the Docker Compose v2 plugin (docker compose version), or Docker Desktop. Both npx @genfeedai/create and the release bundle below need it.
• Node.js 24 or newer (>=24), only for npx @genfeedai/create.
• Free host ports 3000 (web), 3010 (API), 3011 (WebSocket) and 3014 (MCP).
• Plan for at least 15 GB of free disk, plus room for media, backups, and upgrades. This is capacity guidance based on the reported v0.2.15 image footprint; see system requirements.
• RAM: no minimum is published. Tested on 8 CPU / 15 GiB.
• Debian 13 provides Compose v2 in its docker-compose package. With Docker CE, install docker-compose-plugin from Docker's apt repository.

See troubleshooting if the app logs P1001: Can't reach database server at postgres:5432.

Quick start (Community)

One command (recommended):

npx @genfeedai/create my-genfeed

It downloads and verifies the release bundle, prompts for your OpenRouter key, then starts the stack. Checksums, auth, providers, and upgrades: self-hosting guide.

Release bundle (no Node.js): set OPENROUTER_API_KEY in .env to a real key from openrouter.ai/keys before starting. The container exits at start without it.

curl -fLO https://github.com/genfeedai/genfeed.ai/releases/latest/download/genfeed-selfhosted.tar.gz
curl -fLO https://github.com/genfeedai/genfeed.ai/releases/latest/download/genfeed-selfhosted.tar.gz.sha256
sha256sum -c genfeed-selfhosted.tar.gz.sha256
tar -xzf genfeed-selfhosted.tar.gz && cd genfeed-selfhosted-v*
cp .env.example .env
# Edit .env: set OPENROUTER_API_KEY to your real OpenRouter key, then:
docker compose --env-file .env -f compose.yml up -d

On macOS, use shasum -a 256 -c genfeed-selfhosted.tar.gz.sha256 for the checksum step. The API and WebSocket ports bind to 127.0.0.1; a remote browser needs a reverse proxy configured as described in the self-hosting guide.

Surface	Local URL
Web UI	http://localhost:3000
REST API	http://localhost:3010
MCP server	http://localhost:3014
WebSocket	ws://localhost:3011 (live agent replies; keep it reachable)

The bundle pins the image for its release, applies Prisma migrations, and seeds one local workspace. No Genfeed Cloud account is required.

For a first generation, do these in order:

1. Make sure OPENROUTER_API_KEY in .env is a real key (the npx wizard sets it for you). Text generation and the agent need it, and the container refuses to start with an empty or placeholder value. If you change .env later, recreate with the same docker compose up -d command so the container reads the new value.
2. Open http://localhost:3000/sign-up and create your account with Email & password. Sign-up is on by default (BETTER_AUTH_ENABLED=true in .env), and no email provider is needed. The new account gets its own organization and brand.
3. Complete onboarding, then start a task or generation.

Startup checks the OpenRouter key's format and rejects empty or placeholder values. A successful boot does not prove provider balance or model access. Settings → API Keys validates each provider key against the provider before saving it.

Let your coding agent install it

Genfeed is driven by agents, so installing it is a task you can hand to one. Paste this into Claude Code, Codex, Cursor, or any agent with shell access:

Install Genfeed — the open-source content agent — on this machine, then connect
it to yourself over MCP.

1. Check Docker Engine with Compose v2 is available.
2. Download the Community bundle:
   curl -fLO https://github.com/genfeedai/genfeed.ai/releases/latest/download/genfeed-selfhosted.tar.gz
   curl -fLO https://github.com/genfeedai/genfeed.ai/releases/latest/download/genfeed-selfhosted.tar.gz.sha256
   sha256sum -c genfeed-selfhosted.tar.gz.sha256
   tar -xzf genfeed-selfhosted.tar.gz && cd genfeed-selfhosted-v*
   On macOS, use shasum -a 256 -c for the checksum step.
   cp .env.example .env
3. Ask me for my OpenRouter API key and set it in `.env` as
   `OPENROUTER_API_KEY` (a real key; the container exits at start without
   it). Then start the stack:
   docker compose --env-file .env -f compose.yml up -d
   Wait for http://localhost:3000 to answer. Sign-up is open by default; the
   seed also creates one organization (slug `default`) and brand.
4. For Claude Code, register its dedicated content connector:
   claude mcp add --transport http genfeed --scope user http://localhost:3014/mcp/claude
5. Open /mcp, select genfeed and complete browser OAuth. For other clients,
   configure the standard http://localhost:3014/mcp endpoint and authorize in
   the browser; a scoped API-key fallback is available for those clients.
6. List the Genfeed tools to confirm the connection, then stop.

Reference: https://github.com/genfeedai/genfeed.ai/blob/master/docs/self-hosting.md
Docs index for agents: https://docs.genfeed.ai/llms.txt

Already on the hosted product? Skip installation and authorize with browser OAuth. Claude uses https://mcp.genfeed.ai/mcp/claude for brands, drafts, existing assets, scheduling and analytics; create media in Genfeed Playground. Other clients use https://mcp.genfeed.ai/mcp for the full toolset.

The standard MCP preset is approval-first: an agent can generate, draft, and schedule, but publishing waits for a human. What each surface exposes and why is in Agent Surface.

Captured from the real self-hosted app, v0.2.17, 1440×900 dark theme. The posts and the agent conversation are seeded demo content, not a live generation. Regenerate with bun run readme:capture.

Agent: a brief in, drafts out. Both posts wait in Publishing for approval.

Publish: scheduled, draft and published posts in one list.

Automate: the Research to Content workflow template in the visual editor.

Capabilities

• Generate images, video, text, voice, and audio with local or bring-your-own-key execution
• Visual workflow authoring; content library, brand, scheduling, and publishing
• Drive the same loop from the web app, the genfeed CLI, the REST API, or any AI agent over MCP
• PostgreSQL via Prisma; Redis/BullMQ background work
• A Community Docker distribution built from the same AGPL source as the hosted image

Availability differs by deployment mode and configured provider. Read Deployment Modes and Execution Boundaries before relying on a feature for a specific distribution.

Deployment modes

Mode	Who it is for	How you get it
SaaS	Hosted multi-tenant product	app.genfeed.ai
Community	Self-hosters, one organization	Checksummed GitHub release bundle (quick start above)
Desktop	Solo creators on their own Mac	Signed macOS artifacts from desktop-v* tags

Organization billing ships in every image and is gated at runtime (a *.genfeed.ai host / self-host licence) — see the billing section. Managed inference infrastructure and Fleet/LoRA operations live outside this public repository.

Desktop is macOS-first. Mobile and browser/IDE extension sources live in the tree; this repository does not claim a public store listing for them.

How agents work in this repo

This repository is agent-native: most of its code is written by AI agents under human direction, and the tree is laid out so an agent can be productive from a cold clone.

• AGENTS.md and CLAUDE.md — operating rules every agent (and human) follows: type safety, UI primitives, serializers, tenancy filters, commit conventions.
• CONTEXT.md — the glossary. One spelling per concept, used in code, issues, docs, and PRs.
• .agents/ — durable project memory (rules, ADRs under architecture/ADR-*.md, specs) plus build/dev skills for working on the app. MEMORY.md is the index. skills/ at the repo root is different: those are product/content skills the app ships.
• Issues carry EARS acceptance criteria (WHEN … THE SYSTEM SHALL …) so an agent can pick one up and know what "done" means. Triage rewrites weak criteria; it never bounces.
• shipcode:* labels are internal automation. They are visible on issues and PRs; contributors never apply them.
• Agent-authored PRs are welcome when disclosed in the PR body and a named human is accountable for the description and verification. Undisclosed agent-authored PRs are closed. See CONTRIBUTING.md.

PRs are reviewed by an automated pipeline first, then by the maintainer, who alone merges.

Architecture

Genfeed is a Bun/Turborepo monorepo with Next.js clients, NestJS server workspaces, PostgreSQL/Prisma persistence, and Redis/BullMQ queues. The Community image bundles the web app, API, workers, files, notifications, and MCP runtimes into one container and embeds Redis.

apps/
  app/                    Next.js product UI
  server/                 NestJS services and shared server library
  desktop/app/            Electron client (macOS-first release path)
  mobile/app/             Expo/React Native client source
  extensions/browser/app/ Chrome extension source
  extensions/ide/app/     VS Code extension source
packages/                 Shared @genfeedai/* packages
docker/                   Community and hosted image definitions

The public API is REST/OpenAPI. GraphQL appears only in outbound integrations such as Shopify.

The stack is declared, not debated per-PR. Replacing an item requires an accepted ADR before code lands (see GOVERNANCE.md).

Layer	Choice	Why
Runtime + PM	Bun + Turborepo	One toolchain for install, scripts, tests, and bundling
Web	Next.js 16 + React 19	App Router, RSC, and the same client for SaaS, Community, and Desktop
API	NestJS 11	DI, guards, and tenancy/auth enforcement across services
Data	Prisma 7 + PostgreSQL	One schema, typed queries, migrations shipped with every release
Queues	Redis + BullMQ	Generation, publishing, and scheduling are background work
Auth	Better Auth	Self-hostable, org-aware, no vendor account required for Community
Quality	Biome, Vitest, Playwright	Format+lint in one pass; colocated unit tests; E2E tiers per distribution
Distribution	Docker Compose + GHCR	Checksummed bundle pinned to an image

More: Architecture · Deployment Modes · Execution Boundaries · Agent Surface.

Contributing

Contributions are voluntary and unpaid. Genfeed has no paid contribution program; see the contribution policy.

Audience order for this repository is self-hosters, then agent contributors, then human contributors. Development is supported on macOS and Linux (Windows via WSL2). Prerequisites: Node 24, Bun, Docker with Compose v2, a C/C++ toolchain plus python3 (sudo apt-get install -y build-essential python3 on Debian/Ubuntu, xcode-select --install on macOS), and systemd on Linux for dev:setup. Details are in CONTRIBUTING.md.

bun install && cp .env.example .env.local
bun run env:sync local
docker compose -f docker/local/docker-compose.yml up -d postgres redis
bun run dev:setup                  # once per machine
bun run dev:backend:min            # then, in a second terminal:
bun run dev:app                    # → https://app.genfeed.localhost/

Portless HTTPS is the default contributor dev path. Fixed-port dev:debug* commands remain an optional debugging path when Portless cannot be used. Everything else — issue forms and EARS criteria, the PR contract (squash + conventional title + linked issue), the CLA (once per GitHub account per CLA version), agent-authored PR disclosure, and focused verification — is in CONTRIBUTING.md.

Governance is one maintainer plus an AI review pipeline: GOVERNANCE.md. Help and questions: SUPPORT.md. Security reports follow SECURITY.md, never a public issue.

Licence and trademark

• Code: GNU Affero General Public License v3.0 or later — the whole repository
• Contributions: Contributor License Agreement (FSFE FLA 2.1: ICLA.md / CCLA.md), signed once per GitHub account per CLA version via CLA Assistant. A newer CLA version applies to future contributions; prior contributions keep prior rights.
• Name and logo: TRADEMARK.md — the licence covers the code, not the brand

Independently published packages and skills may declare their own license in their package metadata.

Links

Repository docs (docs/ in this tree) are for contributors and self-hosters: self-hosting, deployment modes, architecture, agent surface, and native referral credits. docs.genfeed.ai is the product and API documentation for people using Genfeed. Each side links the other; neither duplicates the other.

• Website · Hosted app · Product docs
• Releases · Project board
• Issues · Discussions
• Pricing and credits