Sign inSign up

hayone/craft-gateway

By hayone

•Updated 5 days ago

Renamed to hayone/craft-web-gateway (no new images here)

Image
0

92

hayone/craft-gateway repository overview

⁠craft-web-gateway

A front door for the storytold craft apps⁠ (PhotoCraft, VectorCraft, LightCraft, FilmCraft, EffectCraft and the rest) with an AI assistant built in.

  • Launcher: one page that lists your apps.
  • Proxy: serves every app under /<app>/ from its own container, by URL or port.
  • Assistant overlay: a chat on top of every app that collapses to a round AI button (✦), floats (drag, resize) or docks to the side while the canvas makes room. The apps carry no chat code.
  • Chat on Claude Code or OpenAI Codex: replies come from Claude Code signed in with a Claude subscription (each person's own, or one shared by the hub), or from Codex signed in with the person's ChatGPT account, so you don't need an API key. The agent works on the document open in your tab, with the app's tools and nothing else.
  • A full chat composer, like Claude Code's: pick the agent, model and effort, show or hide thinking, choose a mode (Manual, Edit automatically, Plan, Bypass permissions; Shift+Tab cycles), attach or paste images, stop a reply, expand each tool call's input and result, see tokens and time per turn, switch between earlier chats, and use slash commands (/model, /effort, /mode, /clear, /compact, /help).
  • Your own AI apps too: the overlay's Connect tab gives each tab its own MCP URL, with a claude.ai connector link, claude mcp add and codex mcp add commands and the steps for a ChatGPT developer-mode app, so your own Claude, Claude Code, ChatGPT or Codex can drive several tabs and apps at once.

Works from any browser, an iPad included: the app runs in the tab, Claude runs on the server.

The gateway stands on its own. craft-vscode⁠, which opens the apps in VS Code panels, doesn't need it: the extension frames the app images directly, and the :remote app images answer the editor themselves (EMBED_ORIGINS on each app container). Until November 2026 the gateway's overlay did that part, with EMBED_ORIGINS and EMBED_FILES on the gateway. The gateway now ignores those two settings and prints a warning when EMBED_ORIGINS is set.

The gateway was called craft-ai-hub until November 2026, and craft-gateway for a day after that. The old GitHub addresses still lead here. Internal names keep the old word "hub", so nothing breaks for running setups: the /_hub/ routes, window.craftHub, the craft-hub:session message, the cookies and HUB_SECRET.

⁠Features

Every feature beyond the launcher and the proxy is optional. Environment variables turn each one on or off, so you run only what you need. The section "Configuration" lists every variable.

FeatureOn whenTurn it off
Launcher and proxyalways
Assistant overlay (chat and the Connect tab)RELAY_URL and MCP_KEY are setLeave RELAY_URL empty
Claude chatclaude is in CHAT_PROVIDERS (the default)CHAT_TOKENS=off, or leave claude out of CHAT_PROVIDERS
Codex chatcodex is in CHAT_PROVIDERS (the default)CHAT_PROVIDERS=claude
A shared Claude accountCLAUDE_CODE_OAUTH_TOKEN is setLeave it empty, or set CHAT_TOKENS=personal
Sign-inBASIC_AUTH or REQUIRE_SIGN_IN=trueLeave both unset
Cloud storage in the apps' File menucraft-mcp has its AUTH_* and STORAGE_S3_* settingsLeave those craft-mcp settings empty

⁠How it works

browser ──▶ craft-web-gateway ──▶ /<app>/        app containers (hayone/<app>:remote)
               │         ──▶ /_relay/…      craft-mcp: the tab's WebSocket and the MCP endpoints
               └─ chat: Claude Code or Codex ──MCP──▶ craft-mcp ──▶ app CLI ──▶ the user's tab
  • craft-mcp⁠ relays MCP calls to the tab. Each browser mints its own signed, expiring relay key per app, and chats are tied to that key, so no two browsers or users share a session.
  • The :remote app images (built in hayone1/Docker_Images⁠) add the page API and MCP connector the overlay uses. Apps without them still open from the launcher, without the assistant.

⁠Run it

Pick an example, copy its .env.example to .env, fill it in, and docker compose up -d:

ExampleFor
basic-auth⁠Trying it out: everything on one machine, user names and passwords in BASIC_AUTH
caddy-https⁠Your own domain with automatic HTTPS (Caddy, Let's Encrypt) and basic auth
oauth2-proxy⁠Sign-in with your OpenID Connect provider (Google, Entra, Keycloak, Authentik, …) through oauth2-proxy⁠
cloud-storage⁠Sign-in through craft-mcp plus personal and shared cloud folders in an S3 bucket, for Open and Save
external-apps⁠Apps that already run elsewhere (other ports or servers): just the hub and the relay
kubernetes⁠The hub, the relay and an app as Deployments, behind an Ingress

Each one publishes only the front door; the apps and the relay stay on the private network.

⁠Accounts

CHAT_PROVIDERS (default claude,codex) lists the agents the composer offers. The model menu groups their models; picking another agent's model starts a new chat.

⁠Claude

Claude chats run on Claude subscription tokens from Claude Code. Create one on any computer signed in to Claude Code (Pro or Max plan):

claude setup-token

CHAT_TOKENS decides whose account a chat uses:

CHAT_TOKENS
personalEveryone adds their own token in the overlay's Account tab. The default without a shared token.
bothTheir own token if they added one, otherwise the hub's CLAUDE_CODE_OAUTH_TOKEN. The default with one.
sharedEveryone uses CLAUDE_CODE_OAUTH_TOKEN.
offNo in-app chat; the Connect tab still works.

A personal token stays in that person's browser: the hub encrypts it (AES-GCM, HUB_SECRET) into an HttpOnly cookie that only /_hub/ receives, so neither the apps' scripts nor the hub's disk ever hold it. People set it up once per browser, from a computer, and then chat from anywhere, an iPad included.

⁠ChatGPT (Codex)

Codex chats run on each person's own ChatGPT plan. In the overlay's Account tab:

  • Sign in with ChatGPT: the hub starts Codex's device-code sign-in and shows a link and a code. Open the link on any device (the iPad you're on works), sign in and enter the code. If ChatGPT refuses the code, turn on device code sign-in for Codex in ChatGPT's security settings.
  • Or paste auth.json: after codex login on a computer, paste ~/.codex/auth.json.

The sign-in is kept in DATA_DIR, encrypted with a key that only that browser's HttpOnly cookie holds, so the disk alone can't open it. Codex refreshes it as it goes, and the hub keeps the newest copy. Mount a volume at DATA_DIR (/data in the image) to keep sign-ins and Codex's chat sessions across restarts; sign-ins unused for 90 days are removed.

Codex runs with its shell, file edits, web search, plugins, browser and sub-agents switched off, read-only in an empty folder and with none of the hub's environment, so the app's MCP tools are all it can use. It reaches them through the hub (/_hub/mcp/…, from the hub itself only), which applies the permission mode before each call.

⁠Configuration

VariableDefault
APPS(required)name=url pairs: photocraft=http://photocraft:8080,vectorcraft=http://localhost:8082. Order is the launcher's.
APP_HOSThttps://{app}.example.org: each app is also served at the root of its own host, for example https://photocraft.example.org/. The proxy in front must pass the original host (Host or X-Forwarded-Host).
RELAY_URLcraft-mcp's internal URL. Without it there is no assistant.
MCP_KEYThe same value craft-mcp has. craft-mcp's PUBLIC_HOST must be <hub origin>/_relay.
CHAT_TOKENSpersonal, or both with a shared tokenWhose Claude account chats use (see above).
CLAUDE_CODE_OAUTH_TOKENThe hub's shared token.
HUB_SECRETderived from MCP_KEYEncrypts personal tokens and ChatGPT sign-ins. Changing it signs every browser out.
CHAT_PROVIDERSclaude,codexThe agents chat offers, in the menu's order.
CHAT_MODEL, CHAT_EFFORTClaude Code'sClaude's defaults when the composer leaves them on Default and Auto.
CHAT_MODELSOpus, Sonnet, Haiku 5.5, Fable 5.1Claude's model menu, as JSON [{"value": "<model id>", "label": "<name>"}].
CODEX_MODEL, CODEX_EFFORTCodex'sCodex's defaults.
CODEX_MODELSGPT-6 Luna, GPT-5.6 Terra, GPT-5.6 LunaCodex's model menu, same JSON.
DATA_DIR/data in the imageChatGPT sign-ins (encrypted) and Codex sessions.
BASIC_AUTHuser:password pairs, comma separated.
REQUIRE_SIGN_INfalsetrue signs people in through craft-mcp's own OpenID Connect client (its AUTH_* settings).
PUBLIC_ORIGINfrom the requesthttps://<host>, used for the sign-in callback. An app's own host (APP_HOST) uses its own origin instead.
PORT8080
⁠Sign-in

Choose one:

  • An auth proxy (recommended): oauth2-proxy, Pomerium, Authelia, Cloudflare Access, or your ingress's auth. Let /_relay/ through without sign-in: MCP clients and the tab's WebSocket authenticate with their relay key, and claude.ai connectors can't sign in.
  • BASIC_AUTH: built in. /_relay/ and /healthz stay open for the same reason.
  • REQUIRE_SIGN_IN: if craft-mcp already signs people in for cloud storage, the hub can use that session. Register <hub origin>/_storage/callback with the provider.

Keep the hub private. Claude subscription tokens are for personal use: with a shared token, every chat on the hub uses that one plan.

⁠Routes

Path
/Launcher
/<app>/…The app, with the overlay injected into its pages
/<app>/_assistant/sessionMints the tab's relay key (craft-mcp /mint)
/<app>/_storage/…, /_storage/…craft-mcp cloud storage and its sign-in
/_hub/cloud.jsCloud storage in the apps' File › Open and Save (see below)
/_relay/…craft-mcp: the tab's WebSocket, /<key>/<app>/mcp
/_hub/overlay.js, /_hub/chat, /_hub/chat/permission, /_hub/tokenThe overlay, its chat and permission answers, and the person's own Claude token
/_hub/codex, /_hub/codex/loginThe person's ChatGPT sign-in (device code or auth.json)
/_hub/mcp/<gate>Codex's MCP connection to the tab, from the hub itself only
/healthzHealth check

On an app's own host (APP_HOST), the app's paths start at / instead of /<app>/: the app at /, /_assistant/session and /_storage/…. The /_hub/ and /_relay/ paths stay the same.

⁠Cloud storage and the assistant connection

The gateway adds both to the app pages; the app images carry neither. cloud.js lends craft-mcp's cloud folders to the app as storage places (window.craftStoragePlaces), which the File › Open and Save dialogs of the remote images list. Before sign-in, the list shows one place that signs in when opened. The overlay makes the tab's relay connection (_assistant/session) and hands it to the app's relay client (window.craftAssistant.use). Remote images from before November 14, 2026 did both themselves, and they still work with this gateway.

⁠Develop

npm install
APPS=photocraft=http://localhost:4101 node server.mjs

Node 22. No build step: server.mjs (proxy, launcher, auth), chat.mjs (chat and permission modes), claude.mjs (Claude Code), codex.mjs (Codex and ChatGPT sign-in), seal.mjs (encryption), public/overlay.js (the overlay).

⁠License

MIT⁠. The craft apps themselves are © their authors under their own licenses (MIT or Apache-2.0); see storytold⁠.

Tag summary

Content type

Image

Digest

sha256:ab37c08b1…

Size

464.8 MB

Last updated

5 days ago

docker pull hayone/craft-gateway