Unified AI Gateway

Unified AI Gateway

Overview

Use the official unified-ai-system MCP server to inspect and exercise a local AI gateway without provider credentials. This skill file provides operating guidance; it does not install the server or change Codex configuration by itself. The official Codex plugin bundles the MCP definition, while skill-only installations require the manual setup below.

Version Note

These are two different things and they are not equal today:

• Current release: v0.8.0. It declares and ships fifteen tool names, and the 60-second demo command in the README names that version. Read it live with node tools/verify-image-roster.mjs 0.8.0, which reports the roster from the image bytes rather than from this file.
• Reviewed and pinned below: 0.4.9. The inspection procedure in this file pins that image's recorded digests because 0.4.9 is the newest version with a completed content review. It carries 9 of the fifteen names: the model-backed enhancement, knowledge retrieval and workflow execution tools arrived at 0.5.0, and the three governance tools at 0.8.0.

Do not substitute a mutable tag for a pinned digest, and do not move the pin to a newer version just because this file looks out of date: a new content review is required first, and the pinned identity is only as good as the review that backs it.

Prerequisites And Setup

1. Confirm that Codex CLI and Docker are installed and Docker is running.
2. If the nine tools are already visible, skip setup and do not register a duplicate server.
3. Explain the first stage: it downloads one reviewed platform from the immutable 0.4.9 multi-platform index into Docker's cache, inspects its metadata and layer history, creates but never starts a temporary container, exports its root filesystem, removes that temporary container, and writes an inspection inventory to a temporary directory. The reviewed platforms are linux/amd64 and linux/arm64. Obtain explicit user approval for those download and inspection changes only.
4. After that first approval, pull the reviewed platform manifest and complete the inspection. Do not execute the image or register it yet:

IMAGE='ghcr.io/happy520ai/unified-ai-system/mcp-server@sha256:751a0d32acd2d6b1da6ad9ac67987fbd1ff36ce26b7160014d8605f18b7907b3'
PLATFORM='linux/amd64' # Use linux/arm64 only on a reviewed ARM64 engine.
REVIEW_DIR="$(mktemp -d)"

docker pull --platform "$PLATFORM" "$IMAGE"
docker image inspect "$IMAGE" --format 'Id={{.Id}} OS={{.Os}} Architecture={{.Architecture}} User={{json .Config.User}} Entrypoint={{json .Config.Entrypoint}} Cmd={{json .Config.Cmd}} Labels={{json .Config.Labels}}'
docker image history --no-trunc "$IMAGE" > "$REVIEW_DIR/image-history.txt"

REVIEW_CONTAINER="$(docker create --platform "$PLATFORM" --pull never --entrypoint /bin/true "$IMAGE")"
docker export --output "$REVIEW_DIR/rootfs.tar" "$REVIEW_CONTAINER"
docker rm "$REVIEW_CONTAINER"

tar -tf "$REVIEW_DIR/rootfs.tar" > "$REVIEW_DIR/rootfs-files.txt"
mkdir -p "$REVIEW_DIR/rootfs"
tar --same-permissions -xf "$REVIEW_DIR/rootfs.tar" -C "$REVIEW_DIR/rootfs"
find "$REVIEW_DIR/rootfs/app" -type f -print > "$REVIEW_DIR/app-files.txt"
: > "$REVIEW_DIR/app-links.txt"
while IFS= read -r -d '' APP_LINK; do
  ls -ld -- "$APP_LINK" >> "$REVIEW_DIR/app-links.txt"
done < <(find "$REVIEW_DIR/rootfs/app" \( -type l -o -type f -links +1 \) -print0)
: > "$REVIEW_DIR/native-binaries.sha256"
while IFS= read -r -d '' NATIVE_BINARY; do
  sha256sum -- "$NATIVE_BINARY" >> "$REVIEW_DIR/native-binaries.sha256"
done < <(find "$REVIEW_DIR/rootfs/app" -type f -name '*.node' -print0)
find "$REVIEW_DIR/rootfs" -type f \( -perm -0100 -o -perm -0010 -o -perm -0001 \) -print > "$REVIEW_DIR/executable-files.txt"
find "$REVIEW_DIR/rootfs" -type f \( -perm -4000 -o -perm -2000 \) -print > "$REVIEW_DIR/suid-sgid-files.txt"
find "$REVIEW_DIR/rootfs/app" -type f \( -name '.env' -o -name '.env.*' -o -name '*.pem' -o -name '*.key' -o -name '*.p12' -o -name '*.pfx' -o -path '*/.ssh/id_*' \) -print > "$REVIEW_DIR/credential-like-files.txt"
find "$REVIEW_DIR/rootfs/app" -type f -name 'package.json' \
  -exec grep -nHE '"(preinstall|install|postinstall|prepare|prepack|postpack)"' -- {} + \
  > "$REVIEW_DIR/lifecycle-hooks.txt"
find \
  "$REVIEW_DIR/rootfs/app/packages/mcp-server/src" \
  "$REVIEW_DIR/rootfs/app/packages/shared-sdk/src" \
  -type f \
  -exec grep -nHE 'child_process|spawn\(|fetch\(|AI_GATEWAY_MCP_URL|process\.env|writeFile|appendFile|unlink|rm\(' -- {} + \
  > "$REVIEW_DIR/runtime-sensitive-code.txt"

If sha256sum is unavailable, use the platform's SHA-256 utility and preserve the same report. Keep the review directory until the report is accepted; its deletion is another filesystem change and requires approval for the exact path.

5. Read every generated inventory and report the inspection before proceeding. Compare it with the versioned image content review. Require OCI index digest sha256:751a0d32acd2d6b1da6ad9ac67987fbd1ff36ce26b7160014d8605f18b7907b3. For linux/amd64, require manifest digest sha256:ff6cf988b01d5fb2e97aabe8e952f6a303dcffe650df5b4dcb0ba3d51ee88c06 and config digest sha256:0c2c0c7b9c7fb7ca24c73d9a903bcf719b079a0b285a3a3269ee3ae059905e97. For linux/arm64, require manifest digest sha256:90318b9e373820f863c1c1addc759be4b5ce186f2ecb6232ee502fad7c6613de and config digest sha256:c2047eb63fdc42bcb16d53fca17d78a4a6fb355cf6320b9aa6688e594371054f. Require source https://github.com/happy520ai/unified-ai-system, revision 342a47313927870bcc696be13c9e5fb922062dac, version 0.4.9, license Apache-2.0, entrypoint docker-entrypoint.sh, and command node packages/mcp-server/src/index.js.

   Report these reviewed risks explicitly: the image uses the default root user; includes Debian shell/package utilities and 11 base-image SUID/SGID files; contains 522 internal pnpm links, three native Node binaries, and eight lifecycle-hook declarations; and starts a child gateway with loopback HTTP. The optional AI_GATEWAY_MCP_URL can make an HTTP or HTTPS connection only when explicitly passed. The registered command below passes no host files, environment variables, or ports and disables container networking. Stop on any mismatch, unexpected link, credential-like file, native binary, hook, privileged file, or sensitive-code behavior.

6. Explain the second stage: it persists a Codex MCP configuration and permits Codex to launch the inspected image in a later task. Obtain a separate explicit approval for registration and activation; the download approval does not carry over.

7. After that second approval, register the reviewed platform digest with pulling, container networking, Linux capabilities, and privilege escalation disabled, then inspect the stored configuration:

IMAGE='ghcr.io/happy520ai/unified-ai-system/mcp-server@sha256:751a0d32acd2d6b1da6ad9ac67987fbd1ff36ce26b7160014d8605f18b7907b3'
PLATFORM='linux/amd64' # Match the reviewed platform inspected above.
codex mcp add unified-ai-system -- docker run --rm -i --pull never --platform "$PLATFORM" --network none --cap-drop ALL --security-opt no-new-privileges "$IMAGE"
codex mcp get unified-ai-system --json

8. Restart Codex or open a new task, then use /mcp verbose to confirm that all nine tools are available - the pinned 0.4.9 image ships nine of the fifteen names the current release declares. Remove the registration when it is no longer wanted:

codex mcp remove unified-ai-system

Removing the registration does not remove the pulled image from Docker's cache. Treat image-cache deletion as a separate host-state change and obtain approval before doing it.

When to Use This Skill

• Use when a user asks whether Unified AI System is healthy or ready.
• Use when a user wants a credential-free gateway chat proof.
• Use when a user asks about the gateway's knowledge, workflow, or workforce surfaces.
• Use when a user wants evidence from the bundled MCP tools rather than a claim inferred from documentation or process exit codes.

Do not use this skill for generic model comparisons, unrelated MCP servers, or deploying a production gateway.

Workflow

1. Confirm that the unified-ai-system MCP tools are available in the current task. If they are absent, follow the approved setup above and wait for a restarted or new task.
2. Call gateway_health, then gateway_readiness, before attempting chat.
3. Select the narrowest additional tool that answers the request.
4. Report returned provider, execution mode, readiness, and blockers exactly.
5. Separate transport success from product, production-readiness, autonomy, or AGI claims.