Genfeed

Genfeed.ai

The open-source content agent.

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.

[!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 the 3-command block below and npx @genfeedai/create need it.
• Node.js 24 (>=24 <25), only for npx @genfeedai/create.
• Free host ports 3000 (web), 3010 (API) and 3014 (MCP).
• About 10 GB of free disk (15 GB recommended); a fresh install measured about 9.5 GB.
• 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)

curl -fLO https://github.com/genfeedai/genfeed.ai/releases/latest/download/genfeed-selfhosted.tar.gz
tar -xzf genfeed-selfhosted.tar.gz && cd genfeed-selfhosted-v*
cp .env.example .env && docker compose --env-file .env -f compose.yml up -d

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. Set OPENROUTER_API_KEY in .env to a real key from openrouter.ai/keys. Text generation and the agent need it. Without it the install-readiness check reports text generation as not ready. Then restart with the same docker compose up -d command so the container reads the new value.
2. Open http://localhost:3000 and create your account. Sign-up is on by default (BETTER_AUTH_ENABLED=true in .env), so the first visitor can register. No email provider is needed for email/password.
3. Complete onboarding, then start a task or generation.

Keys are checked for real. Settings → API Keys validates each provider key against the provider before saving, so placeholder text is rejected there. Keys in .env are never accepted as placeholders either: an empty or template value counts as not configured.

npx @genfeedai/create my-genfeed downloads, checksums, and starts the same bundle. Checksums, auth, providers, and upgrades: self-hosting guide.

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. Start the Community bundle:
   curl -fLO https://github.com/genfeedai/genfeed.ai/releases/latest/download/genfeed-selfhosted.tar.gz
   tar -xzf genfeed-selfhosted.tar.gz && cd genfeed-selfhosted-v*
   cp .env.example .env && docker compose --env-file .env -f compose.yml up -d
3. Wait for http://localhost:3000 to answer. Sign-up is open by default; the
   seed also creates one organization (slug `default`) and brand. Put a real
   OpenRouter key in `.env` as `OPENROUTER_API_KEY` and restart before
   generating.
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](https://app.genfeed.ai/studio/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](docs/agent-surface.md).

![Agent conversation shell in a mocked Community workspace](docs/assets/readme/agent-shell.png)

*Mocked Playwright capture of the agent conversation shell. Fixture data, not a live generation.*

![Publishing desk in a mocked Community workspace](docs/assets/readme/publishing-desk.png)

*Mocked Playwright capture of the Publish desk.*

![Visual workflow authoring in a mocked Community workspace](docs/assets/readme/automation-workflows.png)

*Mocked Playwright capture of Automate workflow authoring.*

## 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](packages/cli), the
  REST API, or any AI agent over [MCP](docs/agent-surface.md)
- 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](docs/deployment-modes.md) and
[Execution Boundaries](docs/execution-boundaries.md) 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](https://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
(`GENFEED_CLOUD` / self-host licence) — see the
[billing section](docs/deployment-modes.md#billing-one-build-a-runtime-gate).
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](.agents/memory/architecture/ADR-AGENT-NATIVE-REPO-PUBLIC.md):
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](AGENTS.md)** and **[CLAUDE.md](CLAUDE.md)** — operating rules
  every agent (and human) follows: type safety, UI primitives, serializers,
  tenancy filters, commit conventions.
- **[CONTEXT.md](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](CONTRIBUTING.md#agent-authored-prs).

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.

```text
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).

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