AI Hub setup for versions 0.22.0 and 0.23.0

Install v0.23.1 once, then follow this guide in order. It includes the Claude Code gateway from v0.22.0 and the new ChatGPT/Codex and WhatsApp integration. You do not need an intermediate v0.22.0 installation. Existing Chat, email/calendar, MCP, users, Gitea projects and worker settings remain in place.

The source baseline was v0.22.0. Your last screenshots showed v0.21.3; check your current footer before upgrading. The new integrations start disabled. Local automated and Inspector tests passed; your real client accounts, reverse proxy and Unraid containers must pass the live checks below before the OpenAI phase is accepted.

Where to start: complete sections 1–2, configure Claude in section 3 if you have not already done it, then configure OpenAI in sections 4–8. WhatsApp is optional in section 9. Section 10 explains the Code screen and section 11 covers troubleshooting and rollback.

1 Upgrade the existing Unraid installation

Where: your Windows update launcher, followed by Portainer and AI Hub.

1. Finish or stop active development tasks. Keep the previous release and make a full data backup. The Windows Git updater pushes code/triggers Portainer; it does not itself back up live Unraid data. In the Unraid terminal, with the two named services currently running and your existing standard folders present, run this backup block before updating. If it reports an error, resolve it before proceeding. Preserve your Portainer environment/deployment configuration separately:

(
  set -eu
  backup_file="/mnt/user/appdata/private-ai-hub/pre-v0.23.0-$(date +%Y%m%d-%H%M%S).tar.gz"
  for folder in data memory vault workspaces; do
    test -d "/mnt/user/appdata/private-ai-hub/$folder"
  done
  trap 'docker start private-ai-hub-memory private-ai-hub >/dev/null' EXIT
  docker stop private-ai-hub private-ai-hub-memory >/dev/null
  tar -C /mnt/user/appdata/private-ai-hub -czf "$backup_file" data memory vault workspaces
  chmod 600 "$backup_file"
  printf 'Backup completed: %s\n' "$backup_file"
)

The included unraid-prepare-update.sh also creates a data/memory/Vault backup when using that separate manual build path; it does not include workspace files. Use the full block above for this guide.

2. Save private-ai-hub-unraid-v0.23.1.zip in the same release folder used by Update-AI-Hub.bat. Do not rename the ZIP. The launcher finds semantic versions recursively; Downloads is not required. Keep your existing .local.cmd and private-ai-hub-deploy.env credentials.
3. To check selection without updating, run Update-AI-Hub.bat --find-only. It must select v0.23.1. If it does not, set AI_HUB_RELEASE_DIR in your existing Update-AI-Hub.local.cmd to the folder containing this ZIP. Run the launcher normally after selection is correct.
4. Let your established updater push the release to Gitea and trigger its configured Portainer webhook. Portainer's Git-backed stack builds/deploys the complete included v0.23.1 configuration. If no webhook is configured, open Portainer → Stacks → private-ai-hub → Pull and redeploy, retaining the existing Git URL, compose path and environment. Keep image re-pull off for these locally built release tags. A restart of old images does not install code or the new Python dependency. The host does not need the unavailable docker compose command.
5. Keep your existing Hub hostname, br0 IP, volumes and worker token. No new Hub port, privileged worker mode or Docker namespace setting is required. Portainer should show your existing stack services running, including the Hub, memory, router, image service and development worker.
6. Reload AI Hub. Confirm the footer says v0.23.0. If it shows an older version, check the deployed image tag/build and then refresh the browser.
7. Open ordinary Chat, test an existing /v1 client, and open Code → Development connections → Test worker sandbox. Expect status: ready and all five protection checks true. A blank saved token field means the secret stays hidden; leave it blank to keep the token.
8. Startup creates /data/backups/hub-before-openai-<timestamp>.db before the additive OpenAI migration. If the Claude migration has not run yet, it also creates its backup. These DB snapshots do not replace your full master-key/mem0/Vault backup.

Pass condition: version 0.23.0, existing Chat works, the existing worker is ready, and your existing projects remain visible. Do not enable remote integration until this passes.

2 Verify the coding model and Ollama queue

Where: profile → AI Model Connections, Admin → Routing & API, and Code.

1. Open Ollama on Unraid. Test/refresh the connection so the Hub receives current model sizes and runtime GPU data. Keep your real 12 GB GPU limit and reserve settings; automatic coding selection uses those limits.
2. Confirm qwen3.5:9b is installed and enabled. For the first practice task, enter this exact ID in AI route for this task and choose Continue task. Later use hub-code to let the Hub select a fitting coding model.
3. This release disables codellama:13b in Hub model policy. It does not delete Ollama files. CodeLlama is a dense model; your 49% CPU / 51% GPU display indicates actual CPU offload, not MoE activation. Automatic coding avoids a model observed with substantial CPU offload and checks advertised tool support before tool-enabled chat. Check /api/show connectivity if tool-capability discovery fails.
4. If using OpenRouter, test the OpenRouter connection and refresh its model list. Select the exact currently available vendor/model ID. A unique permitted OpenRouter connection can route this form even when its cached list is stale. Removed or unavailable provider models can still fail upstream. Multiple OpenRouter connections require an explicit connection/alias choice.
5. Under Chat access, include the connection you intend to use. Cloud connections remain unavailable to private chats. Do not label a cloud endpoint Local to force it through privacy checks.
6. Start one local Code task and a second local chat. The second generation should show its queue position until the first completes. Different Ollama models use the same queue when configured with the same endpoint URL, including local preprocessing and Hub-initiated mem0 embedding/extraction. The supplied stack sets the Hub's MEMORY_OLLAMA_URL to the memory companion's OLLAMA_URL; keep these URLs equal when customizing the stack. Optional memory requests skip after five seconds waiting for a busy model and use the existing unavailable-memory fallback. A memory write reports failure rather than claiming it was saved; retry it when the model is free.
7. Optional: in the Ollama container's environment, set OLLAMA_MAX_LOADED_MODELS=1 and OLLAMA_NUM_PARALLEL=1, then recreate that container through its normal management screen. These settings reduce competing loads on one GPU. The Hub queue coordinates requests within one running Hub process; unrelated applications, direct memory-service calls outside the Hub, and differently named URLs to the same Ollama server are outside that coordination.

Pass condition: the task reports the selected model, tool-enabled chat uses a tool-capable model, and the second local request waits visibly. A fitting model improves latency but does not prove correctness; inspect actual changes and test output.

3 Set up the retained Claude Code gateway

Complete these steps once. If your gateway already works, verify its project/checkpoint setup and continue to section 4. Claude uses /anthropic; OpenAI uses /mcp; the existing /v1 route stays separate.

Claude step 1 Configure a native Anthropic connection

1. Sign in as an admin. Open your profile → AI Model Connections.
2. Add or open an Anthropic connection. Enter the provider API credential

there, save and test it. The Hub encrypts it; clients never receive it.

3. Assign the connection to the users who may use it under Admin → Routing & API.
4. Open Admin → Claude Code → Native provider and allowed models.
5. Select that connection. Enter exact model IDs discovered by the provider,

one per line. No obsolete model IDs are automatically added.

6. Optionally map claude-default, claude-fast, claude-powerful and

local-fast to permitted native model IDs. For the first live test use an

actual model ID so Claude can recognize its capabilities directly.

7. Save the provider policy. Enable the gateway and Save flags.

The existing connection's enabled state, user access and model enable/disable

settings remain authoritative. Private projects allow only local or ZDR

connections. An ordinary Anthropic cloud account is not automatically ZDR:

use it only with a project explicitly permitted to use cloud processing.

Do not relabel a provider to bypass your privacy policy.

Endpoint override is optional. Remote credentials require HTTPS; HTTP is

allowed only for a connection designated local. Overrides must speak native

Anthropic Messages. OpenAI/Ollama JSON chat endpoints cannot be substituted.

Timeout is configurable from 10–1800 seconds. The retry policy is client:

the Hub forwards retryable statuses, retry headers and original error bodies,

but never automatically repeats a generation that might already be billed.

Claude step 2 Create a project and an owned Hub key

1. On Claude Code → Projects, choose Add a project.
2. Link an existing Hub Development project for repository diagnostics/indexing,

or enter an external project's name and Git URL. A repository identity does

not depend on an absolute Windows path. Branch isolation is optional.

3. Keep Safe Optimization selected. Set the project's privacy deliberately.
4. Save. Copy its Project ID from the project details.
5. Under Your Claude keys, enter a name, select the project scope, provider(s)

and explicit model permissions. Expiration is optional.

6. Create Hub key and copy it immediately. It is displayed once and stored as

a hash. Never commit this key, place it in CLAUDE.md or share it here.

Generic Hub keys and the old global proxy key do not authenticate to the new

namespace. Claude keys cannot access the existing /v1 API or administrative

settings. Revoking a key or disabling its user stops subsequent requests.

Claude step 3 Windows Claude CLI

In PowerShell, replace each placeholder on your computer:

$env:ANTHROPIC_BASE_URL = "https://aihub.mini.bebz.net/anthropic"
$env:ANTHROPIC_AUTH_TOKEN = "<YOUR_OWNED_AI_HUB_KEY>"
$env:CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY = "1"
$env:ENABLE_TOOL_SEARCH = "true"
$env:AI_HUB_PROJECT_ID = "<PROJECT_ID>"
$env:ANTHROPIC_CUSTOM_HEADERS = "X-AI-Hub-Project: $env:AI_HUB_PROJECT_ID"
claude --model "<ALLOWED_NATIVE_MODEL_ID>"

The base URL ends in /anthropic, not /v1/messages. The token is the Hub key,

not the upstream key. A project-scoped key works without the project header;

a conflicting header is rejected. For persistence, merge these values into

the env object in %USERPROFILE%\.claude\settings.json, or use a local secret

helper. Do not overwrite your existing settings or put a key in shared project

settings. The Hub also accepts its owned key in x-api-key for compatible

clients; Bearer is preferred for this setup.

Run /status: it should show the Hub Anthropic base URL and gateway token.

Use /model to confirm authorized discovery. A session alias stays pinned to

its initial provider/model; changing the alias during that session returns a

clear conflict instead of silently switching thinking/cache state.

Actual CLI command execution remains on the machine running Claude. To execute

remotely, run the CLI on the intended development host or use AI Hub's existing

project Development worker. This gateway does not synchronize Windows files.

Claude step 4 Claude Desktop Code tab

The current official Desktop gateway setup uses a third-party inference form,

not CLI environment settings:

1. Help → Troubleshooting → Enable Developer Mode; let the app restart.
2. Developer → Configure Third-Party Inference.
3. Choose gateway inference. Enter

https://aihub.mini.bebz.net/anthropic as the gateway base URL.

4. Choose Static API key and Bearer authentication. Enter your owned Hub key.
5. Select an authorized native model and restart/start a Code session.

Managed organization settings can make the form read-only. In this gateway

mode, Desktop sessions run locally; Desktop's SSH/cloud environment picker and

Remote Control are not available. Use the CLI on Unraid if that is the execution

location you want. Test your installed Desktop version explicitly before

treating Desktop compatibility as confirmed.

Official references:

CLI gateway connection,

gateway protocol guide,

Desktop gateway setup.

Claude step 5 Memory, checkpoints, skills and MCP

Enable Project mem0 memory only if wanted. The user's existing memory preference

must also be enabled. Save durable facts under project/repository/branch scope;

all those scopes include the user and project identity. User scope is an

explicit cross-project scope. A client key cannot write user-wide memories.

Keep credentials, raw logs and giant source dumps out of durable context.

Select a project, enter its short architecture summary and create a checkpoint.

Resume context searches mem0 for the current task and returns the latest

checkpoint plus relevant indexed files, within the configured bootstrap target

(default ~2000 estimated tokens). Nothing is injected into ordinary requests.

Unavailable memory returns a status and leaves the native gateway usable.

Click Download manual Claude skills and extract that ZIP into the project's

root on the computer running Claude. It contains six manual skills plus the

small clients under .claude/; it contains no keys. Invoke

/ai-hub-project-status, /ai-hub-resume-project, /ai-hub-create-checkpoint,

/ai-hub-debug-production, /ai-hub-deployment or /ai-hub-token-audit.

Python 3 must be available on that computer. The deployment workflow reads

state; approval/release/deployment still happens in the Hub.

For MCP access, add this to your local Claude MCP configuration, adapting

the Python executable/path. Supply the three variables through the process

environment or secure local configuration; do not put secrets in a committed

.mcp.json:

{
  "mcpServers": {
    "ai-hub-project": {
      "command": "python",
      "args": [".claude/ai-hub-project-mcp.py"]
    }
  }
}

The facade advertises eight small on-demand tools. Search returns short approved

metadata; load a selected schema explicitly. Read tool calls are checked again

against current server/user approvals; write tools are blocked for client keys.

Keep any other MCP servers connected to Claude subject to their own permissions.

ENABLE_TOOL_SEARCH=true controls Claude's native deferred loading; the gateway

preserves tool_reference, defer_loading, beta headers and server tools.

Disabling gateway Tool Search returns an explicit error for deferred requests,

never a silent expansion.

Hub tasks create checkpoints at Ready for review, acceptance, undo, model

handoff and release/deployment submission. Submission is not proof of deployed

application health. Existing indexed projects refresh after acceptance/undo.

Client compaction hint headers can snapshot an existing checkpoint. External

Claude commits, deployments, area changes and session resets are not observable

automatically: call the checkpoint skill/tool at those boundaries.

Claude step 6 Token modes, budgets and offload

Transparent and Safe modes preserve native request semantics and stable prompt

prefixes. The raw body is preserved byte-for-byte for actual model IDs. Alias

routing changes only the model; field/array order is retained. No timestamps,

dynamic telemetry, memory or regenerated schemas enter cached prefixes.

Aggressive is explicit per project. Its compaction operates on durable

checkpoints, deduplicating retained decisions/constraints/files/tests and keeping

old checkpoints recoverable. It does not automatically summarize or rewrite

ordinary requests. Long preserved state that exceeds the checkpoint limit

requires the user to refine it rather than silently discard constraints.

Local offload is separately disabled by default. Enable its global flag and a

project's explicit authorized local/ZDR Ollama/Colibri model for bounded

SEARCH/SUMMARIZATION/LOG_ANALYSIS preprocessing. Code generation, architecture

and security reasoning are not automatically delegated. Model preferences

recommend a model for a fresh task; they do not switch every Claude turn.

local-fast is a native-protocol alias; direct Ollama offload uses the separate

project tool, not an Anthropic/OpenAI translation shim.

Token Policies supports user/project/provider/model/key limits, UTC daily,

Monday-based weekly and calendar-monthly periods. Warn thresholds are

50/75/90/100%. Soft limits require an explicit one-hour override at 100%.

Hard limits use upstream input counting plus a reserve margin (32 tokens or 2%, whichever is larger) and reserve the maximum output before

generation, atomically across concurrent requests. Spending limits require

configured rates per million tokens: input/output/cacheRead/cacheWrite/

cacheWrite1h. No prices are fabricated. Existing provider daily/monthly limits

also apply to this gateway ledger. Fallback offers a configured fresh-session

model; it does not automatically migrate an active session or bypass privacy.

The ledger covers native gateway generations; model discovery and client token-counting requests have separate non-billable metadata entries. It does not cover historical OpenAI/Hub chat

usage or separate Ollama preprocessing billing. Partial/disconnected requests

retain protective reservations when final billing is unknown. An admin can

reconcile a finished reservation via

POST /api/claude/usage/<request-id>/reconcile with tokens, cost, and a

credential-free provider evidence reference. Never clear a reservation by

guessing the request was free.

AI Usage provides periods, custom ranges, token/cache/cost totals, local charts

and metadata breakdowns. Cache hit rate is cached-read tokens divided by all

input tokens, including cache creation. Schema capacity avoided is an estimate,

not measured token savings. Exact CLAUDE.md/file-read/tool-result attribution

cannot be reconstructed from provider aggregate usage alone. Unknown cost and

incomplete usage are displayed explicitly. Optional tracking can be disabled;

records needed for budget protection remain enabled.

Claude step 7 Live acceptance checks — required after deployment

1. Admin → Claude Code → Run Claude Code Compatibility Test. Its individual

results use an isolated mock upstream; they do not certify live Anthropic.

2. Start Claude CLI with the scoped Hub key. Verify /status, /model, normal

messages, a streaming answer and a tool-use/tool-result round trip.

3. Connect an actual MCP server; enable Tool Search and request a deferred tool.

Verify reference/loading behavior in Claude debug output and Hub usage.

4. Reuse a sufficiently long identical cached prefix across two real requests

to a model that supports caching. Verify cache-creation and cache-read tokens

in AI Usage. An upstream cache hit cannot be proven with mock counters.

5. Save/retrieve a checkpoint and mem0 fact; use a second account/project and

confirm isolation. Temporarily disable memory/offload independently and

verify a normal message continues to work.

6. Set a small test-key hard token limit. Confirm it blocks before generation,

then remove it. Check a soft-limit override and private-provider rejection.

7. Test your installed Desktop Code tab separately. Record client/model versions,

outcomes and request references. Do not share API keys or full private prompts.

For a reverse proxy, disable response buffering on /anthropic/, preserve

request/response headers, permit SSE and align read timeouts with your provider

timeout. The Hub returns X-Accel-Buffering: no; the actual proxy configuration

must still be verified. TLS terminates at your existing reverse proxy.

4 Prepare the shared project and public MCP endpoint

Where: AI Hub → profile → Claude Code, then Admin → ChatGPT / Codex, and your reverse proxy.

1. In Claude Code → Projects, create/select the same project that Claude uses. For development actions and repository indexing, link it to the existing Code project. Do not create a second copy for Codex.
2. Confirm repository identity and optional branch scope. Refresh its repository index. Save a short checkpoint with the objective, completed work, decisions, changed files, actual tests/results, blockers and next steps. Checkpoints now show their originating client.
3. OpenAI clients are external recipients. Only explicitly non-private projects appear in OAuth consent. If this project contains sensitive data, keep it private and use local tools; do not turn privacy off just to complete setup. For a suitable project, deliberately permit external processing. User/project/repository/branch ownership still applies.
4. Open Admin → ChatGPT / Codex. Set Public HTTPS origin to https://aihub.mini.bebz.net (no /mcp suffix). Save. The displayed endpoint should be https://aihub.mini.bebz.net/mcp.
5. Enable ChatGPT / Codex MCP, Shared checkpoint tools, Repository retrieval, and Record context estimates. Enable Developer plugin to download the package. Enable Company Knowledge search and fetch if wanted. Save integration settings.
6. Leave Read-only sources eligible for external clients unchecked initially. Later enable only individually approved infrastructure sources; each user must grant these again during OAuth consent. Project permission does not automatically disclose email, calendar, PHI or all infrastructure tools.
7. At your reverse proxy, route this hostname to the existing Hub service. Preserve the canonical Host, Authorization, MCP method/name/version/session headers and request body. Set X-Forwarded-Proto: https from the trusted TLS proxy; strip any client-supplied value. Preserve paths for /mcp, /oauth/, /.well-known/ and authenticated project citation URLs. Disable caching for these routes. Permit POST and DELETE and allow a 180-second read timeout for worker actions.
8. Keep /anthropic streaming rules and /v1 routing unchanged. An extra proxy login page, CAPTCHA or IP restriction that blocks the remote MCP client will break discovery. Protect private data with Hub OAuth rather than making project resources anonymous. The backend port should be reachable only from trusted networks/proxies.
9. Open https://aihub.mini.bebz.net/.well-known/oauth-protected-resource and https://aihub.mini.bebz.net/.well-known/oauth-authorization-server in a browser. Expect JSON with your canonical MCP resource/issuer and authorization, token and registration endpoints. An unauthenticated MCP call should return 401 with a Bearer discovery challenge, not project content.
10. Click Run isolated compatibility tests in the integration page. Record the result. These use a temporary fixture, not your production accounts.

Pass condition: HTTPS and metadata work, the endpoint challenges unauthenticated requests, and local compatibility tests pass. The endpoint advertises a maximum of 21 curated tools; disabled flags/scopes reduce the list.

OAuth uses your existing Hub login, S256 PKCE, one-use short-lived codes, hashed access/refresh tokens, refresh rotation, explicit project/scope consent and immediate server-side revocation. Client metadata registration and dynamic registration are supported. No Hub key belongs in plugin files or skill instructions. Authorization is rechecked on every call; an anonymized client session ID is only an audit correlation value.

5 Test the live endpoint with MCP Inspector

Where: Windows terminal and the Inspector browser window, before ChatGPT registration.

1. Install/use Node.js 22.19 or newer. Run:

npx @modelcontextprotocol/inspector@latest

2. Open the local browser URL printed by Inspector. Choose Streamable HTTP and set the URL to https://aihub.mini.bebz.net/mcp.
3. Use Inspector's OAuth/authentication flow. Sign in to AI Hub, choose only your test project, grant Read plus Checkpoints initially, and approve. Keep development access off for this first read test.
4. Connect and list tools. Call list_projects, get_project_status, get_project_context with max_tokens: 250, and get_latest_checkpoint. Use the Project ID returned by list_projects.
5. Inspect annotations. Reads must have readOnlyHint: true; checkpoint creation is a write; development actions identify possible destructive effects. Call create_checkpoint with a short harmless state and retrieve it. Inspect an empty search result and a bad project ID; neither should leak another project.
6. If Company Knowledge is enabled, call search and then fetch using a returned ID. Open its source URL in a browser signed into the same Hub account. A signed-out browser must not receive private project content.
7. Revoke this authorization in AI Hub → ChatGPT / Codex → Connected clients. The next Inspector call must fail authentication. Reauthenticate only if needed for later tests.

The release was checked with official Inspector 2.9.0 in both modern and legacy protocol modes against an isolated HTTP server. Repeat against your real HTTPS endpoint; that verifies your actual proxy and login.

6 Connect ChatGPT and ChatGPT Work

Where: your ChatGPT account/workspace and the Hub consent page.

1. In ChatGPT, open Settings → Security and login → Developer mode. Availability depends on your account/workspace policy.
2. Open Plugins, select +, enter AI Hub Developer, and under Connection enter https://aihub.mini.bebz.net/mcp. Create the connection and inspect discovered metadata. This follows the current OpenAI connection guide.
3. Authenticate with your existing AI Hub account. If the consent page says sign in, open the Hub login link, sign in, return and reload the consent page. Do not paste a provider API key.
4. Select your shared project. Grant Read, Checkpoints, and optionally Development actions for isolated edits/testing. Grant only individually approved connector sources. Approve. The callback returns to the initiating client.
5. In a fresh ordinary ChatGPT conversation, enable/select or mention the connection from the tools/plugin menu. Say: Use AI Hub Developer to list my projects and show the current status of AI Hub. Confirm real tool calls rather than an answer based on memory.
6. In a fresh ChatGPT Work task, enable the same connection and say: Resume development of AI Hub. Read the latest checkpoint and retrieve only the context needed for the next task. Report the branch, blockers and tests actually recorded. The task should call the Hub without asking for your old Claude transcript.
7. For a small development test, request a new isolated task, file changes and a saved test command. The client calls create_development_task and apply_development_action; inspect the same task in Hub Code. Discuss forbids edits, Review requires Hub approval before side effects, and Develop permits edits/testing in the isolated copy. Approval, acceptance and production release remain in the Hub.
8. Ask: Create a checkpoint before we switch models. Include the actual tests and next steps. Inspect its client_origin and state in the Hub.
9. If the product/workspace does not provide Work or write tools, use the supported read workflows and record Work acceptance as pending. A local protocol check does not prove that your installed product can execute the complete workflow.

Company Knowledge uses the read-only search and fetch tools and authorized citation URLs. Availability depends on the workspace's knowledge integration policies. It never exposes development actions through the knowledge pathway. Your ChatGPT/Codex subscription selects the client's model; the Hub does not proxy its internal model traffic or know its total billed model tokens.

7 Install the developer plugin and connect Codex

Where: AI Hub → ChatGPT / Codex, Windows Explorer and your OpenAI client's Plugins screen.

1. Click Download developer plugin in the Hub or use the separate openai-ai-hub-developer-v0.23.0.zip. Extract it to a stable folder. Keep plugin.json, mcp.json, .mcp.json, .codex-plugin/plugin.json, skills/ and README together. The dynamic Hub download inserts your configured HTTPS endpoint. Keep this plugin ZIP's name; the Hub updater must select the full Unraid release ZIP.
2. The portable package uses the current Agent Plugins manifest and OpenAI extension metadata; the .codex-plugin overlay is included for Codex compatibility. It contains no credentials. Do not use the old ai-plugin.json ChatGPT plugin format.
3. To register a Windows personal local plugin, place the plugin at %USERPROFILE%\.codex\plugins\ai-hub-developer. Create %USERPROFILE%\.agents\plugins if needed. In %USERPROFILE%\.agents\plugins\marketplace.json, add the entry below. If the file already exists, merge the plugins entry instead of overwriting other plugins:

{
  "name": "ai-hub-local",
  "interface": {"displayName": "AI Hub"},
  "plugins": [{
    "name": "ai-hub-developer",
    "source": {"source": "local", "path": "./.codex/plugins/ai-hub-developer"},
    "policy": {"installation": "AVAILABLE", "authentication": "ON_INSTALL"},
    "category": "Productivity"
  }]
}

4. Restart/refresh your desktop client's plugin directory, install AI Hub Developer, and authenticate when asked. If your client restricts local plugins, use its workspace administrator's supported publication/install flow. The OpenAI plugin packaging guide describes current marketplace and publishing requirements.
5. For CLI-only Codex MCP access, use these commands instead of duplicating the plugin's connection:

codex mcp add ai-hub-developer --url https://aihub.mini.bebz.net/mcp
codex mcp login ai-hub-developer
codex mcp list

6. Grant only your shared project and required scopes in the Hub consent screen. For worker tests that take over one minute, set tool_timeout_sec = 180 under the existing [mcp_servers.ai-hub-developer] entry in %USERPROFILE%\.codex\config.toml. Preserve your other settings. See Codex MCP configuration.
7. Start a fresh Codex task with the installed plugin enabled, or with the CLI MCP connection. Say: Continue the current AI Hub development. Retrieve the latest shared checkpoint and the relevant repository context before editing. Confirm it sees the checkpoint made in ChatGPT Work, and the same project/branch.
8. The plugin has manual skills: resume-project, project-status, create-checkpoint, investigate-error, debug-deployment, release-version, and token-audit. Select/invoke a skill in the client's supported skill picker. The skills retrieve information on demand. MCP-only CLI access works without the plugin skills.
9. A locally installed package is not automatically a published OpenAI directory plugin. If you submit/publish, enter any supplied domain challenge in Hub Admin → ChatGPT / Codex. The Hub serves that current value at /.well-known/openai-apps-challenge; leave it blank when no challenge is active. Do not invent a permanent challenge or registered app ID.
10. If the publication flow requires .app.json, use the actual technical app ID created by your registered connection. Follow the current OpenAI packaging instructions for that registration; the source package deliberately does not fabricate an ID.

8 Verify the cross client acceptance scenario

Where: fresh Claude, ChatGPT Work and Codex sessions, then the Hub.

1. Claude Code performs a small real task and creates a checkpoint through its existing project skill. Note the project ID, branch, changed files and tests.
2. Start fresh ChatGPT Work and say Resume development of AI Hub. It must identify that project, read Claude's checkpoint, retrieve relevant memory and current repository state, without importing the Claude conversation.
3. Work performs another small isolated development task, runs a meaningful test through the worker, and creates a checkpoint with the actual result and next step.
4. Start fresh Codex and say Continue the current AI Hub development. It must retrieve Work's latest checkpoint and continue the same project accurately.
5. Repeat a read with a second Hub user/project. The first project's ID, knowledge ID and cursor must be rejected. Revoke one client and verify its next request fails. Change the project to Private and confirm external access fails.
6. In Hub ChatGPT / Codex, inspect recent tools, successes/failures and returned context estimates. On get_token_usage, provider model usage and estimated MCP-supplied context are separate. Source bytes are recorded where measured (file/log retrieval); the Hub does not invent a repository-wide MB reduction or know total ChatGPT/Codex model consumption.
7. Record client versions, test commands, exit codes, checkpoint IDs and request references. Do not store credentials or full private conversations in the report.

Acceptance remains pending until every step works with your real accounts. The release includes automated isolated Work-style edits/testing and Codex-style handoff checks; those are not live OpenAI account tests.

To revoke access: profile → ChatGPT / Codex → Connected clients → Revoke. Remove the client connection/plugin too if desired. To update: deploy the new Hub release, Refresh the ChatGPT connection metadata, replace/update the local plugin package, and start a fresh client task. Existing valid grants remain scoped; grant extra projects/sources through a new consent flow rather than editing tokens.

9 Optional WhatsApp through WAHA or Beeper

Choose WAHA on Unraid for an always-on server setup. Beeper is also supported, but its Desktop app must stay running and its API must be reachable from Unraid. This is a bridge integration, not WhatsApp Business Cloud API registration. Live bridge/account behavior is not yet certified.

WhatsApp step 1 Deploy and pair WAHA

Where: Portainer → Stacks → Add stack, then WAHA's dashboard and your phone.

1. Create a separate stack named ai-hub-whatsapp. Copy the optional template scripts/whatsapp-waha-stack.yml; set WAHA_IMAGE to the image/tag supported by your chosen WAHA edition, and supply new WAHA_API_KEY and WAHA_DASHBOARD_PASSWORD values through Portainer's environment fields. Do not reuse Hub/provider credentials.
2. Use a free LAN port such as 3001 mapped to the bridge's port 3000. Restrict it to your LAN/firewall; do not expose the bridge API publicly. The template persists sessions at /mnt/user/appdata/ai-hub-whatsapp/sessions. Pin the tested image tag after your initial trial. WAHA deployment and API security describe image/security settings.
3. Open http://<UNRAID_LAN_IP>:3001/dashboard. Sign in as admin with the dashboard password, and connect using the bridge API key. Create/start the default session.
4. If using NOWEB, enable its store before scanning the QR code so chat history endpoints work. Use session config:

{"name":"default","config":{"noweb":{"store":{"enabled":true,"fullSync":false}}}}

5. When the dashboard displays a QR code, open WhatsApp on your phone → Linked devices → Link a device and scan it. Wait for session status WORKING. See WAHA pairing and NOWEB history storage. Your WAHA edition/engine must support chat history endpoints; otherwise choose a supported engine rather than interpreting missing history as an AI failure.

WhatsApp step 2 Connect the Hub and read one chat

Where: AI Hub → profile → WhatsApp.

1. Add a connection. Choose WAHA on Unraid. Enter http://<UNRAID_LAN_IP>:3001, the WAHA API key, session default, and Read only. Keep Use local models only on. Save.
2. Reopen it and click Test connection, then Find chat IDs. The LAN URL must be reachable from the Hub container; Windows localhost or a service name on an unrelated Docker network will not work. IDs are obtained from the bridge, not guessed phone/group names.
3. In Allowed chats, add aliases and exact IDs, one per line, for example family=<EXACT_GROUP_ID>. Save. Only those chats can be read/summarized or used as send targets.
4. Choose the allowed chat and click Read messages, then Summarize. Summaries use your selected existing Hub model route and bounded recent messages. No read receipt is sent by these read calls. The first release handles text; attachments/media and full historical archives are not ingested.
5. If you want manual replies, change Permission to Read and reply, save, type a reply, click Review and send, and confirm the exact chat/text. Verify actual delivery on WhatsApp: a bridge accepted result is not proof of delivery.

WhatsApp step 3 Optional commands sent to the AI

1. Use a dedicated control chat whose ID is already in Allowed chats. A second sender/account/device is needed: messages identified by the bridge as fromMe are deliberately ignored to prevent reply loops.
2. In Message the AI through WhatsApp, enter the control chat ID, exact allowed sender IDs from Read messages, and your desired Hub AI route. Choose Read and reply, enable AI command replies, and Save. This explicitly authorizes automatic replies to allowed commands.
3. Wait for the initial poll to establish a baseline; old messages are ignored. Send a fresh /hub ask What can you help me with? from the allowed sender into the control chat. Replies go only to that control chat.
4. To summarize an allowed group, send /hub summarize family, where family matches your alias. Ordinary messages, other senders and unlisted chats must not trigger replies.
5. Polling is approximately every 20 seconds. Commands older than ten minutes are ignored. Deduplication is persistent and automatic sends are not retried after ambiguous failures, so a failed command may need a new message. Toggle AI command replies off to stop the bot while keeping manual reading enabled.

WhatsApp step 4 Beeper alternative

1. Install/open Beeper Desktop, connect WhatsApp there, and enable its Desktop API/Integrations feature. Create a token through Beeper's supported local authentication flow. Use the endpoint shown by your installed app; do not assume it is reachable remotely.
2. Because a loopback Desktop API cannot be reached from Unraid, provide a secured LAN proxy/tunnel accessible to the Hub, with authentication and firewall restrictions. Keep Beeper running. This release does not install a Windows sync agent or configure that tunnel automatically.
3. In Hub WhatsApp choose Beeper Desktop API, enter that LAN endpoint and API token, then follow the same Read only → Test → Find chat IDs → allowlist workflow. Beeper IDs may differ from WAHA IDs.
4. Consult Beeper Desktop API for the installed app's authentication and endpoint setup. Test reading and delivery before enabling command replies.

10 Use the Code screen after setup

Where: Code → select your project → Conversation, Files, Changes and Checks.

1. Keep one practice task selected. Leave the duplicate stopped/paused. The task list and selected conversation now refresh automatically, including completed and paused tasks, roughly every 2.5 seconds while Code is visible. If connectivity drops, the screen shows Reconnecting and resumes polling. Saved drafts/settings are preserved.
2. For the greeting test, use python -m unittest discover -s tests as the saved Test command, confirm you reviewed it, and save Project settings. Leave other commands blank if the standard-library project does not need them. Set qwen3.5:9b for the first continued task if the old task was using CodeLlama.
3. At Needs your input, inspect the reason. Approve only the pending action you intend, or enter instructions and Continue task. A step limit or summary without files/tests is not a completed implementation.
4. At Ready for review, open Changes and verify hello.py and tests/test_hello.py have meaningful diffs. Open Checks: expect the real command, at least two passing tests and exit code 0. A check marked Files changed since this check must be rerun.
5. Only then choose Accept changes. For linked projects, the accepted task is merged through Gitea before being accepted into the project. Open Gitea to verify the commit. For your practice project, stop here; production deployment is unnecessary.
6. For a deployable project, configure its compose path, variables and Portainer environment in the existing project settings; enable deployment only for that project. After acceptance, choose Release, enter a new version and explicitly enable deployment if wanted. Portainer pulls the Gitea release tag. A submitted stack update and passing application health are separate checks.
7. Undo accepted task creates a repository revert/restores changed files; Restore previous deployment selects the prior deployed tag. Neither automatically restores application databases or external side effects. Keep backups for data rollback.

11 Troubleshooting and rollback

Rollback to v0.22.0: disable OpenAI flags and WhatsApp bot/connections, revoke OpenAI grants, stop Hub writes and keep a current full backup. The new checkpoint client_origin column is additive, but v0.22.0 uses a six-column positional insert: its checkpoint writes are not compatible with the seven-column upgraded table. For the supported rollback, stop Hub/memory services, restore the matching full pre-v0.23.0 data backup, then redeploy the saved complete v0.22.0 release and original settings. Use the older ZIP explicitly with your Windows launcher; automatic discovery selects the latest ZIP. Post-backup work is lost. Do not simply restart the old image against the upgraded DB.

Rollback to a version before v0.22.0: use the matching full pre-upgrade backup as above. If retaining any later DB state through a manually reviewed schema rollback, also disable/revoke all Claude-specific keys before installing older code, which does not understand their scope. The retained revocation procedure is in CLAUDE_GATEWAY_SETUP.md. That advanced schema rollback is not automated by this release.

Full data rollback: stop Hub/memory services, restore the full matching pre-upgrade backup including DB, master key, mem0, Vault and needed workspace data, then redeploy that release. Post-backup work is lost. Never overwrite a running DB or replace master.key independently. Restoring only code is a different operation from restoring data.

12 Record live setup results

Leave unavailable checks Pending, not Passed. The OpenAI phase is accepted only after the full Claude → fresh Work → fresh Codex handoff succeeds without transcript import.