⭐ If you like this project, star it on GitHub. It helps a lot!
Features • Prerequisites • Quick Start • Self-Hosting • Agent Access • Local Development • Roadmap
Free, frontier-level image generation. Built to run on the Google Cloud console using its $300 free trial credit.
A self-hosted AI studio for image and music generation, built on Google's Gemini Enterprise platform (formerly Vertex AI). No subscription, no middleman markup, no consumer-app data mining. Your entire library lives in SQLite and flat files on your own disk, and the only third party involved is Google's API, billed at raw rates with your own key. Clone the repo, run the setup script, and you have a private creative studio running on your own hardware.
If you've used Higgsfield, it's the same gallery-first experience, except you own the server, the library, and the costs: no subscription, just your own Google API key.
HomeField_demo.mp4
Mobile screenshots
 |
 |
- Models: Nano Banana 2 (fast) and Nano Banana Pro (flagship)
- Reference images: attach up to 14 per prompt to guide style or composition
- Aspect ratios: Auto, 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
- Resolution: 512, 1K, 2K, or 4K output
- Batch generation: run multiple generations from the same prompt at once
- Search grounding: optionally anchor generations in live web context
- Text-to-music via Google Lyria
- Duration: 30s, 60s, 3 min, 4 min
- Controls: BPM, intensity, instrumental toggle, custom lyrics, watermark
- Models: Lyria 3 Pro Preview and Lyria 3 Clip Preview
- Project workspaces to separate generations by project or client
- Prompt template library with categories, favourites, and "For You" recommendations based on your history (powered by Google's text-embedding-004 model)
- Cross-device sync so everything follows your account across devices and tabs
- MCP server at
/api/mcpso AI agents can generate into your library - Per-agent workspaces so agent output never lands in your own
- Scoped API keys with spend ceilings, an expiry, and one-click revocation
- Visible provenance: every agent-made image is badged and fully inspectable
- Bundled skill that teaches the agent to spend carefully, iterate by reference, and show its results in the chat
- Live pending states: generations started anywhere show up on every open session in real time
- Shared gallery for broadcasting to a public live feed
- Multi-user support with admin-controlled account approval
- Admin panel for managing users, roles, and backups
Important
HomeField runs entirely on Google Cloud infrastructure. You need a Google Cloud Console account to use it. If you have a Google account, you already have access at cloud.google.com. New accounts get $300 in free credits valid for 90 days, which covers months of regular use.
- A Google Cloud project with the Gemini Enterprise API (
aiplatform.googleapis.com) enabled - A service account JSON key with the Vertex AI User role (
roles/aiplatform.user; the console may show it under the newer Gemini Enterprise branding) - Docker and Docker Compose (install Docker)
Note
Google renamed Vertex AI to Gemini Enterprise in April 2026. The console shows the new branding, but the underlying APIs, roles, and this app's configuration are unchanged.
Note
No GPU required. All generation runs on Google's infrastructure.
HomeField itself is free (MIT). Generation runs on your own Google Cloud account:
- New GCP accounts get $300 in free credits (valid 90 days), which covers months of regular use
- After that, you pay Google's standard Gemini Enterprise per-image rates directly. No markup, no subscription, no minimum
- Your prompts and images go to Google's API for generation and nowhere else; the library, accounts, and metadata stay on your server
Paste this into any AI coding agent (Claude Code / Cowork, Codex, Hermes, or Openclaw) and it will walk you through the entire setup:
I want to self-host HomeField Studio, an AI image and music generation web app that runs on Google's Gemini Enterprise platform (formerly Vertex AI). Help me get it running from scratch.
Work through these steps in order, confirm each one is done before moving on, and ask me for any information you need along the way:
1. Check that Docker and Docker Compose are installed. If not, help me install them.
2. Clone the repo:
git clone https://github.com/Stink-O/Homefield.git
cd Homefield
3. I need to set up a Google Cloud project with the Gemini Enterprise API (aiplatform.googleapis.com, formerly the Vertex AI API) enabled. Walk me through what to do in the Google Cloud Console. If I already have a project, use that.
4. Walk me through creating a service account with the "Vertex AI User" role (roles/aiplatform.user, may appear under Gemini Enterprise branding) and downloading a JSON key. Then help me strip all the newlines out of it so it's a single line.
5. Run the setup script and help me fill in each prompt:
bash setup.sh
Or if I'd rather do it manually, help me create homefield.env in the repo root with:
AUTH_SECRET (generate with: openssl rand -base64 32)
AUTH_TRUST_HOST=true
AUTH_URL (the URL I'll access the app from, e.g. http://localhost:3000)
GOOGLE_APPLICATION_CREDENTIALS_JSON (the single-line JSON key from step 4)
GENERATION_PROVIDER=vertex
NODE_ENV=production
Then start it:
docker compose -f docker-compose.homelab.yml up -d
6. Once the app is running, open it in a browser. You'll be directed to /setup to create the first admin account. Fill in a username, email, and password.
Let me know when everything is up and I can log in.
Tip
The agent walks you through Docker setup and first login. Google Cloud Console steps (project creation, service account, API enable) require manual browser actions in your Google account.
git clone https://github.com/Stink-O/Homefield.git
cd Homefield
bash setup.shThe setup script handles configuration, pulls the image, and starts the container.
Create homefield.env in the repo root:
AUTH_SECRET= # openssl rand -base64 32
AUTH_TRUST_HOST=true
AUTH_URL= # e.g. http://localhost:3000
GOOGLE_APPLICATION_CREDENTIALS_JSON= # service account JSON as a single line
GENERATION_PROVIDER=vertex
REPLICATE_API_TOKEN= # only needed if GENERATION_PROVIDER=replicate
NODE_ENV=productionThen start it:
docker compose -f docker-compose.homelab.yml up -dEvery push to master publishes a new image to ghcr.io/stink-o/homefield:latest. Watchtower will pick it up and restart the container automatically.
git clone https://github.com/Stink-O/Homefield.git
cd Homefield/web
cp .env.example .env.local
npm install
npm run dev:httpOpen http://localhost:3000. For HTTPS in dev, drop cert.pem and key.pem in web/ (use mkcert) and run npm run dev instead.
| Variable | Required | Description |
|---|---|---|
AUTH_SECRET |
Yes | Generate with openssl rand -base64 32 |
AUTH_TRUST_HOST |
Yes | Set to true |
AUTH_URL |
Yes | Full URL the app is served from |
GOOGLE_APPLICATION_CREDENTIALS_JSON |
Yes | Service account JSON as a single line |
GENERATION_PROVIDER |
No | vertex (default) or replicate |
REPLICATE_API_TOKEN |
No | Only needed if using Replicate |
- Enable the Gemini Enterprise API (
aiplatform.googleapis.com) in Google Cloud Console - Create a service account with the Vertex AI User role (
roles/aiplatform.user) and download the JSON key - Remove all newlines from the file so it's one line, paste it as
GOOGLE_APPLICATION_CREDENTIALS_JSON
If you'd rather skip the Google Cloud setup for image generation, HomeField can route image models through Replicate:
- Create a Replicate account and generate a token under Account settings, API tokens
- Set these in your env file:
GENERATION_PROVIDER=replicate
REPLICATE_API_TOKEN=r8_...The image models map to Replicate's hosted versions of the same Google models (see web/lib/replicate.ts):
| HomeField model | Replicate model |
|---|---|
Nano Banana 2 (gemini-3.1-flash-image) |
google/nano-banana-2 |
Nano Banana Pro (gemini-3-pro-image) |
google/nano-banana-pro |
Trade-offs to be aware of:
- Simpler setup: just a token, no Google Cloud project, service account, or JSON key
- Same underlying models, billed at Replicate's per-image rates instead of Google's
- Automatic fallback: if a Replicate call fails and
GOOGLE_APPLICATION_CREDENTIALS_JSONis also configured, the request retries on Vertex, so you can run both for resilience - Rate limits: Replicate throttles bursts on new accounts; HomeField retries 429s automatically, but large batches may queue
- Music generation still needs Google credentials. Lyria is only available through the Google API, so a Replicate-only setup covers images but not music
When you open HomeField for the first time, you'll be directed to /setup to create the initial admin account. Fill in a username, email, and password, and that's it. The setup page disables itself once an admin exists.
After that, new accounts require admin approval before they can generate anything. Everything is managed from the Admin panel in the app.
HomeField exposes a Model Context Protocol server at /api/mcp, so an AI agent can generate images in your library, browse what it made, and search the prompt template library. It speaks the 2026-07-28 revision and falls back to the 2025 Streamable HTTP transport for older clients.
Set it up from Settings → Agent access. The flow walks through naming the agent, choosing where it may write, what it may do, and what it may spend, then hands you a ready-to-paste command for your client.
An API key is the agent's identity, so the destination rule lives on the key rather than on each request — an agent cannot talk its way into a workspace you did not grant it.
| Mode | Behaviour |
|---|---|
| Own workspace (default) | Creating the key mints a workspace named after the agent. Everything lands there and nowhere else. |
| Pinned | The key is locked to one existing workspace you pick. |
| Any | The agent chooses per request from your workspaces. |
Nothing writes to your Main workspace unless you allow it. The confinement applies to reads too: a key restricted to one workspace cannot browse the rest of your library.
Every agent-generated image carries a violet badge with the agent's name on its gallery card and a Created by row in the lightbox. The label is stored alongside the image, so it survives revoking the key. Otherwise these are ordinary images — restore to prompt, use as reference, download, move, and delete all work exactly as they do for your own. The header filter scopes the gallery to Everything / Yours / Agents.
Claude Code connects directly:
claude mcp add --transport http homefield http://your-host:3000/api/mcp --header "Authorization: Bearer hf_live_..."Claude Desktop and claude.ai require a public HTTPS URL — they reject localhost and LAN addresses. Either put HomeField behind a TLS reverse proxy (Tailscale Funnel and Cloudflare Tunnel both work), or bridge to it with mcp-remote. The setup flow generates the right config for each.
Warning
An API key is a bearer token. Over plain HTTP it travels in the clear on your network — worth a TLS proxy if your LAN is not fully trusted. Keys expire after 90 days by default and can be revoked at any time from Settings.
If a client reports a connection failure, this says which half is wrong:
node web/scripts/mcp-check.mjs http://your-host:3000 hf_live_...It separates an unreachable server from a rejected key, lists the tools the key can actually see, and exits non-zero on failure.
| Generating | generate_image, get_generation_status, cancel_generation |
| Library | list_images, get_image, move_image |
| Organising | list_workspaces, create_workspace |
| Prompts | search_templates, save_template |
| Uploading (off by default) | create_upload_url |
| Destructive (off by default) | delete_image, publish_image, unpublish_image |
Editing is generate_image with reference_image_ids — there is no separate edit tool. Tools return a small preview inline plus a link to the full-resolution file, so a 4K image never floods the agent's context.
New keys get the generate scope only. Uploading, deleting and publishing must be granted deliberately, and a key can also be capped to a maximum model, a maximum resolution, and a daily image budget.
Every finished image comes with a download_url: a short-lived signed link that fetches the full-resolution file with no auth header, so an agent can drop it into a project's assets folder with a single curl. The link covers one image and expires after about ten minutes.
In Claude Code, ask to see an image and the agent will download it and post it straight into the chat. Once you have asked, it keeps doing so for every image it makes in that session, including refinements, so you can react and redirect before it spends on the next one. Say you no longer want them inline to turn it off.
The server ships a skill (skill://homefield-image-studio/SKILL.md) that teaches all of this, along with how to choose a model and resolution, how to iterate by reference, and how to stay inside the key's workspace and budget. Clients that support the MCP skills extension pick it up on connect; the server's instructions point everything else at it.
To edit a file the agent already has on disk — a screenshot, a crop, a photo in the project — it calls create_upload_url and gets back a signed, single-use link plus the id the file will occupy. One curl -F puts the file in the key's workspace, and the id goes into reference_image_ids like any other library image. The bytes never pass through the model's context, which is what makes this work: inlining a file as base64 in a tool call fails for anything beyond a few kilobytes. The link expires after about ten minutes and dies with the key. Uploads need the upload scope, are capped at 20 MB, and do not count against the daily image budget.
By default every account generates against the instance-wide Google key. Admins can move any user to their own service-account key from the Admin panel, in which case that user's generations — and their agents' — bill to their own Google project.
| Layer | Technology |
|---|---|
| Framework | Next.js 16 (App Router) |
| Language | TypeScript 5 |
| Styling | Tailwind CSS 4 |
| Animation | Framer Motion |
| AI (Image and Music) | Google Gemini Enterprise, formerly Vertex AI (Gemini, Imagen, Lyria) |
| AI (Fallback) | Replicate |
| Database | SQLite via Drizzle ORM + better-sqlite3 |
| Auth | NextAuth v5 |
| Real-time | Server-Sent Events (SSE) |
| Image processing | Sharp |
| Audio waveforms | Wavesurfer.js |
- Video generation
- Prompt chaining and multi-step workflows
- Agentic use (MCP server / tool API for AI agents to generate and manage images)
- Local model support (Ollama / ComfyUI)
- Shareable prompt packs
- Native mobile app