[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-1280":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":23,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":30,"readmeContent":31,"aiSummary":32,"trendingCount":16,"starSnapshotCount":16,"syncStatus":33,"lastSyncTime":34,"discoverSource":35},1280,"gpt-image-canvas","mrslimslim\u002Fgpt-image-canvas","mrslimslim","Local professional AI canvas built with tldraw.","https:\u002F\u002Fgithub.com\u002Fmrslimslim\u002Fgpt-image-canvas",null,"TypeScript",636,88,4,3,0,37,47,314,111,9.85,"MIT License",false,"main",true,[27,28,29],"ai","ai-tools","aiimagegenerator","2026-06-12 02:00:25","# GPT Image Canvas\n\n[English](README.md) | [简体中文](README.zh-CN.md)\n\nLocal AI image canvas for prompt-to-image generation, reference-image generation, and multi-step Agent planning. It combines tldraw, Hono, SQLite, and GPT Image 2 into a local-first creative workspace.\n\nCurrent version: `v0.2.0`.\n\n## Preview\n\n![GPT Image Canvas preview](docs\u002Fassets\u002Fapp-preview.png)\n\n## What It Does\n\n- Create and arrange AI-generated images on a tldraw canvas.\n- Generate from text prompts or use selected canvas images as references.\n- Save project state, generation history, and generated assets locally.\n- Configure image providers from `.env`, the in-app provider dialog, or Codex login.\n- Plan multi-image work in the Agent tab, then execute DAG-based generation jobs around a plan node.\n- Optionally back up new generated images to Tencent Cloud COS.\n- Browse local outputs in Gallery, including rerun, locate, download, and upload status.\n\n## Requirements\n\n- Node.js `24.15.0`. The repo includes `.nvmrc` and `.node-version`.\n- pnpm `9.14.2`. The version is pinned in `package.json`.\n- An OpenAI API key with access to `gpt-image-2`, an OpenAI-compatible image endpoint, or a Codex login completed inside the app.\n- Docker Desktop or a compatible Docker Engine, only if you want the Docker workflow.\n\nActivate the pinned package manager with Corepack if needed:\n\n```sh\ncorepack prepare pnpm@9.14.2 --activate\n```\n\n## Quick Start\n\nWindows PowerShell:\n\n```powershell\npnpm install\nCopy-Item .env.example .env\npnpm dev\n```\n\nmacOS\u002FLinux:\n\n```sh\npnpm install\ncp .env.example .env\npnpm dev\n```\n\nOpen the web app at [http:\u002F\u002Flocalhost:5173](http:\u002F\u002Flocalhost:5173).\n\n`pnpm dev` starts both local services:\n\n- API: [http:\u002F\u002F127.0.0.1:8787](http:\u002F\u002F127.0.0.1:8787)\n- Web: [http:\u002F\u002Flocalhost:5173](http:\u002F\u002Flocalhost:5173), proxying `\u002Fapi` to the API service\n\nThe app can start without credentials. Without a usable provider, `\u002F` shows the credential-aware homepage and generation requests return `missing_provider` until you configure one.\n\n## Configure Generation\n\nThe default provider order is:\n\n1. Environment OpenAI-compatible config from `.env` or runtime variables.\n2. Local OpenAI-compatible config saved in the app.\n3. Codex login fallback.\n\nFor the simplest API-key setup, edit `.env`:\n\n```env\nOPENAI_API_KEY=\nOPENAI_BASE_URL=\nOPENAI_IMAGE_MODEL=gpt-image-2\nOPENAI_IMAGE_TIMEOUT_MS=1200000\n```\n\nLeave `OPENAI_BASE_URL` empty for the official OpenAI API. Set it to an OpenAI-compatible `\u002Fv1` endpoint when using another provider, and set `OPENAI_IMAGE_MODEL` if that endpoint expects a different image model name.\n\nYou can also open the top-right `配置` dialog and save one local OpenAI-compatible provider. Local keys are stored in SQLite under `DATA_DIR`, returned only as masked values, and preserved until you enter a replacement key.\n\n## Routes\n\n- `\u002F` is the credential-aware homepage. It offers `Codex 登录` and `接入 API` when no provider is available.\n- `\u002Fcanvas` is the working canvas. Without a provider, it redirects back to `\u002F`.\n- `\u002Fgallery` remains available even without credentials, so local work can still be viewed.\n\nEnvironment values are read-only in the provider dialog. If you change `.env`, restart the API or Docker container.\n\n## Using the Canvas\n\nThe right-side panel has two main flows:\n\n- `Manual`: enter a prompt, choose size\u002Fquality\u002Fformat, and generate. Selecting one image shape switches the flow into reference-image generation.\n- `Agent`: describe a multi-image task, optionally select up to three canvas images, review the generated plan node, then execute it.\n\nAgent planning uses a separate OpenAI-compatible chat configuration from the image provider. Save it in the Agent LLM settings with API key, Base URL, model, timeout, and `supportsVision`.\n\nWhen `supportsVision` is enabled, selected images are attached to the planning request as multimodal inputs. When disabled, selected images are passed only as reference handles for later image generation. Agent messages are not persisted in this version; plan nodes already on the canvas are saved with the normal canvas snapshot.\n\nPlan execution is DAG-based. Independent jobs can run in parallel, jobs that reference generated outputs wait for their dependencies, and `Retry failed` reruns failed or blocked jobs while keeping successful upstream outputs. A single plan is capped at 16 generated images, including intermediate anchors.\n\n## Cloud Backup\n\nGenerated images are always saved locally first. If Tencent Cloud COS is enabled from the in-app cloud storage dialog, new images are also uploaded to:\n\n```text\n\u003Ckey-prefix>\u002FYYYY\u002FMM\u002F\u003CassetId>.\u003Cext>\n```\n\nThe COS dialog is prefilled from:\n\n- `COS_DEFAULT_BUCKET`\n- `COS_DEFAULT_REGION`\n- `COS_DEFAULT_KEY_PREFIX`\n\nSaving COS settings performs a test upload and delete before the config is persisted. `SecretKey` is stored in local SQLite and only returned as a masked value. COS upload failures do not fail image generation; the image remains available locally and the history item shows the upload failure.\n\n## Project Layout\n\n```text\napps\u002Fapi         Hono API, SQLite storage, provider selection, Agent planning\u002Fexecution\napps\u002Fweb         Vite + React + tldraw web app\npackages\u002Fshared  Shared contracts and constants\ndocs             Project docs and preview assets\ndata             Local runtime data, ignored by Git\n```\n\n## Scripts\n\n| Command | Description |\n| --- | --- |\n| `pnpm dev` | Start API and web dev servers. |\n| `pnpm api:dev` | Start the API dev workflow. |\n| `pnpm web:dev` | Start the Vite web dev workflow. |\n| `pnpm typecheck` | Typecheck shared, web, and API packages. |\n| `pnpm build` | Build shared, web, and API packages. |\n| `pnpm start` | Start the built API package. |\n| `pnpm --filter @gpt-image-canvas\u002Fapi smoke:planner` | Check Agent plan validation fixtures. |\n| `pnpm --filter @gpt-image-canvas\u002Fapi smoke:agent` | Check Agent config and WebSocket basics. |\n| `pnpm --filter @gpt-image-canvas\u002Fapi smoke:executor` | Check Agent DAG execution with a fake image provider. |\n\nBefore completing code changes, run:\n\n```sh\npnpm typecheck\npnpm build\n```\n\nFor UI changes, run `pnpm dev` and verify the Vite app in a browser at [http:\u002F\u002Flocalhost:5173](http:\u002F\u002Flocalhost:5173).\n\nIf `better-sqlite3` reports a `NODE_MODULE_VERSION` mismatch after switching Node versions, rebuild it:\n\n```sh\npnpm --filter @gpt-image-canvas\u002Fapi rebuild better-sqlite3 --stream\n```\n\n## Docker\n\nDocker Compose builds shared contracts, the web app, and the API into one image. The API serves both `\u002Fapi` and the built web bundle from one localhost port. SQLite data and generated assets persist in host `.\u002Fdata`.\n\nWindows PowerShell:\n\n```powershell\nCopy-Item .env.example .env\ndocker compose config --quiet --no-env-resolution\ndocker compose up --build\n```\n\nmacOS\u002FLinux:\n\n```sh\ncp .env.example .env\ndocker compose config --quiet --no-env-resolution\ndocker compose up --build\n```\n\nOpen [http:\u002F\u002Flocalhost:8787](http:\u002F\u002Flocalhost:8787) by default. Set `PORT` in `.env` before starting Compose to use a different localhost port.\n\nUse `docker compose config --quiet --no-env-resolution` when real credentials exist. Plain `docker compose config` expands env files and can print secrets.\n\nCompose defaults `SQLITE_JOURNAL_MODE=DELETE` and `SQLITE_LOCKING_MODE=EXCLUSIVE` to avoid SQLite shared-memory errors on Docker Desktop bind mounts. Avoid running `pnpm dev` and Docker against the same `data\u002F` directory at the same time.\n\nThe Compose build accepts these network-related build args:\n\n- `NODE_IMAGE`\n- `NPM_CONFIG_REGISTRY`\n- `APT_MIRROR`\n- `APT_SECURITY_MIRROR`\n\nThe default `NODE_IMAGE` is `node:24.15.0-bookworm-slim`.\n\n## Runtime Data And Secrets\n\n`DATA_DIR` defaults to `.\u002Fdata` locally and `\u002Fapp\u002Fdata` in Docker. It contains:\n\n- `gpt-image-canvas.sqlite`: project state, generation history, asset metadata, provider config, Agent LLM config, optional COS config, and Codex OAuth token records.\n- `assets\u002F`: generated image files.\n\nDo not commit `.env`, `.ralph\u002F`, `.codex-temp\u002F`, `data\u002F`, generated images, SQLite databases, or build output.\n\nTreat `data\u002Fgpt-image-canvas.sqlite` as sensitive after saving local provider keys, Agent LLM keys, COS secrets, or Codex tokens. The app is designed for local workstation use; do not expose it publicly without adding your own authentication and network controls.\n\nIf a real API key was ever committed, rotate the key. Git ignore rules prevent future leaks, but they do not remove secrets from existing Git history.\n\n## Troubleshooting\n\n- Missing provider: add `OPENAI_API_KEY` to `.env` and restart, save a local provider from `配置`, or complete `Codex 登录`.\n- Codex login fails: confirm the machine can reach `https:\u002F\u002Fauth.openai.com`, keep the login dialog open, and restart the flow if the user code expires.\n- Custom endpoint fails: confirm `OPENAI_BASE_URL` points to an OpenAI-compatible `\u002Fv1` endpoint and supports the configured image model.\n- Agent cannot plan: save the Agent LLM config separately from the image provider config. If `supportsVision` is enabled and the request fails, try fewer or smaller selected images.\n- Agent plan cannot execute: confirm the normal image provider is configured; Agent planning and image generation use separate configs.\n- Port conflict: set `PORT` for API\u002FDocker. For web dev, stop the process on `5173` or run `pnpm web:dev -- --port 5174`.\n- Docker cannot pull the base image: restore Docker Hub access or set `NODE_IMAGE` to an equivalent cached Node `24.15.0` image.\n- SQLite `SQLITE_IOERR_SHMOPEN` in Docker: keep the Compose SQLite defaults, rebuild, and make sure no local API process is using the same database.\n- SQLite `SQLITE_CORRUPT`: stop all app processes, back up `data\u002F`, then restore from backup or remove the SQLite files to create a clean database. Files under `data\u002Fassets\u002F` can be kept.\n- Stale local state: stop the app and remove files under `data\u002F`. This deletes local project state, history, and generated assets.\n\n## Upgrading\n\nBefore upgrading an older local install, back up runtime data:\n\nWindows PowerShell:\n\n```powershell\nCopy-Item -Recurse data data-backup-before-upgrade\ndocker compose up --build\n```\n\nmacOS\u002FLinux:\n\n```sh\ncp -R data data-backup-before-upgrade\ndocker compose up --build\n```\n\nRebuild the web app and API together after an upgrade.\n\n## Codex Notes\n\nCodex can work directly in this repository. Let it read `AGENTS.md`, then use the pinned package manager:\n\n```sh\npnpm install\npnpm typecheck\npnpm build\n```\n\nKeep credentials out of prompts and logs. For Ralph-driven work, read `docs\u002Fralph-execution.md`; keep PRDs under `.agents\u002Ftasks\u002F`, runtime state under `.ralph\u002F`, and scratch files under `.codex-temp\u002F`.\n\n## License\n\nMIT\n\n## Friendly Links\n\n- [LINUX DO - 新的理想型社区](https:\u002F\u002Flinux.do\u002F)\n","GPT Image Canvas 是一个基于tldraw构建的本地专业AI画布工具，用于从文本提示生成图像、参考图像生成以及多步骤Agent规划。它集成了tldraw、Hono、SQLite和GPT Image 2技术，提供了一个以本地优先的创意工作空间，支持在画布上创建和排列AI生成的图像，并允许用户通过文本提示或选择画布中的图像作为参考来生成新图像。此外，项目状态、生成历史和生成的资产可以保存在本地，且可通过配置环境变量或应用程序内的对话框设置图像提供商。此工具适合需要进行创意设计、图像生成及管理的场景使用，如广告设计、产品原型制作等。",2,"2026-06-11 02:42:46","CREATED_QUERY"]