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 or newer. 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.
- 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.
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
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:
- 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.
- 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.
- 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 — operating rules for every agent (
CLAUDE.md imports it)
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/
web/ Next.js product UI (app.genfeed.ai)
marketing/ Next.js marketing site (genfeed.ai)
docs/ Documentation site
server/ NestJS services and shared server library
desktop/ Electron client (macOS-first release path)
mobile/ Expo/React Native client
extension/ Chrome extension
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 26, 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
bun run dev:backend:min
bun run dev:web
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
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.