Kiwi Gateway

Kiwi Gateway is the local execution bridge for Kiwi Mesh. It registers local Codex/Claude runners with Mesh over an outbound socket, exposes optional local HTTP/WebSocket APIs, and runs agent tasks against local workspaces.

Install

Install the latest published package from the public npm registry:

npm install -g @kiwi-mesh/gateway@latest --registry=https://registry.npmjs.org

The primary CLI command is kwg. The long command kiwi-gateway is also available for compatibility. The daemon manager command is kiwi-gateway-daemon.

Verify the installed version and daemon entrypoint:

npm view @kiwi-mesh/gateway version --registry=https://registry.npmjs.org
kwg version
kiwi-gateway-daemon help

If a machine uses an npm mirror or private registry by default, keep the explicit --registry=https://registry.npmjs.org flag when installing or upgrading to avoid stale cached versions.

One-command Start

npm install -g @kiwi-mesh/gateway@latest --registry=https://registry.npmjs.org && kwg start \
  --mesh-url https://mesh.example.com \
  --account [email protected] \
  --token CHANGE_ME_TOKEN \
  --gateway-name "Local Gateway"

This starts the gateway in the foreground and persists the Mesh connection settings to ~/.kiwi-gateway/config.env with private file permissions.

Initialize Once, Start Later

kwg init \
  --mesh-url https://mesh.example.com \
  --account [email protected] \
  --token CHANGE_ME_TOKEN \
  --gateway-name "Local Gateway"

kwg start

Default local state:

~/.kiwi-gateway/config.env
~/.kiwi-gateway/gateway.db
~/.kiwi-gateway/codex
~/kiwi-workspaces/default

Commands

kwg start
kwg restart
kwg init
kwg doctor
kwg version
kwg help
kiwi-gateway-daemon help

kwg restart stops an existing Kiwi Gateway process for the configured local API port, then starts a fresh foreground gateway process.

kwg start options:

--mesh-url <url>
--account <email>
--token <token>
--gateway-id <id>
--gateway-name <name>
--workspace-root <path>
--codex-bin <path>
--claude-bin <path>
--host <host>
--port <port>
--config <path>

Configuration precedence is CLI flags, environment variables, config file, then defaults.

Daemon Supervisor

kiwi-gateway-daemon installs and operates the foreground kwg start process as an OS-managed service. The service manager keeps the process alive, and a separate watchdog checks http://127.0.0.1:3939/api/health every minute to recover from hung or unhealthy states. The watchdog requires two consecutive failed checks before restarting, stores bounded consecutive-failure state in ~/.kiwi-gateway/watchdog-state.json, and resets that state after a healthy check. A single transient timeout never terminates a live Gateway task.

Common commands:

kiwi-gateway-daemon install
kiwi-gateway-daemon uninstall
kiwi-gateway-daemon start
kiwi-gateway-daemon stop
kiwi-gateway-daemon restart
kiwi-gateway-daemon status
kiwi-gateway-daemon logs
kiwi-gateway-daemon doctor

Service defaults:

macOS:   ~/Library/LaunchAgents/com.kiwi.gateway.plist
Linux:   /etc/systemd/system/kiwi-gateway.service
Windows: KiwiGateway via NSSM, or Task Scheduler when NSSM/admin rights are unavailable. The fallback restart path ends the scheduled task before starting it again.

The daemon reads ~/.kiwi-gateway/config.env by default. Keep sensitive settings in that file or in the platform service environment. At minimum, set explicit paths for Codex when using the Codex.app bundled CLI:

KIWI_GATEWAY_HOME=~/.kiwi-gateway
CODEX_HOME=~/.codex
CODEX_BIN=/absolute/path/to/codex
AGENT_API_HOST=127.0.0.1
AGENT_API_PORT=3939
MESH_URL=https://mesh.example.com
MESH_GATEWAY_ID=CHANGE_ME_GATEWAY_ID
MESH_GATEWAY_NAME=Local Gateway

Platform examples:

# macOS user LaunchAgent + watchdog
kiwi-gateway-daemon install \
  --kwg-bin "$PWD/dist/src/cli.js" \
  --daemon-bin "$PWD/dist/src/daemon.js" \
  --node-bin /opt/homebrew/opt/node@24/bin/node
launchctl print "gui/$(id -u)/com.kiwi.gateway"

# The installer builds a self-contained artifact under ~/.kiwi-gateway/app.
# LaunchAgent and its watchdog
# use the stable Homebrew Node executable and never execute the Git checkout or
# a Node binary from the Codex runtime cache. If Gateway-owned data remains on
# /Volumes/wd, grant /opt/homebrew/opt/node@24/bin/node Full Disk Access once
# in macOS.

# Linux systemd service + timer
sudo kiwi-gateway-daemon install --system --kwg-bin "$(command -v kwg)"
systemctl is-active kiwi-gateway.service
systemctl status kiwi-gateway-watchdog.timer

# Windows NSSM service, falling back to scheduled tasks if NSSM is unavailable
kiwi-gateway-daemon install --kwg-bin "%APPDATA%\\npm\\kwg.cmd"
Get-Service KiwiGateway

status reports service state, local port listening, health endpoint state, Codex runner availability, last mesh acceptance found in local logs or journald, and restart metadata when the OS exposes it. doctor checks kwg, Node, CODEX_BIN, CODEX_HOME, config permissions, loopback Mesh URLs, and whether port 3939 is occupied by a non-gateway process.

Doctor

kwg doctor

doctor checks Node.js, writable gateway state, writable workspace root, local SQLite, Mesh config, and whether codex / claude commands are available. Claude is optional unless enabled.

Local API

Default API endpoints:

http://127.0.0.1:3939
ws://127.0.0.1:3939/api/agent/ws

Examples:

curl http://127.0.0.1:3939/api/health

curl -X POST http://127.0.0.1:3939/api/agent/run \
  -H 'content-type: application/json' \
  -d '{"sessionKey":"api:demo","agentId":"codex","workspace":"~/kiwi-workspaces/default","prompt":"Say hello","mode":"new"}'

Mesh Registration

Mesh registration is outbound. The local gateway opens a Socket.IO connection to Mesh and sends local agents, workspaces, capabilities, endpoint id, and connectionMode: "outbound". Your local gateway does not need a public inbound URL.

Create a gateway access token in Mesh Settings, then run:

kwg init --mesh-url https://mesh.example.com --account [email protected] --token CHANGE_ME_TOKEN
kwg start

For multiple Mesh endpoints, set MESH_ENDPOINTS in ~/.kiwi-gateway/config.env.

Edge Runtime

When the Mesh channel is enabled, Gateway opens independent outbound Socket.IO WebSocket connections to /edge/general and /edge/trade-critical. Commands are persisted in the local SQLite relay before Gateway acknowledges delivery. Agent, general trade, and critical trade work use isolated queues, so Agent or General congestion cannot block a critical cancel command.

Configure local Trade Node discovery with a JSON array. Only Unix domain sockets and loopback TCP addresses are accepted:

TRADE_NODE_GRPC_ENDPOINTS=[{"endpointId":"trade-node-1","address":"unix:/tmp/kiwi-trade-node.sock","ttlMs":30000,"signingPublicKeyFile":"/etc/kiwi-trade-node/signing/public.pem"}]

Signed trade envelopes are verified before they enter a local trade queue. Configure the public half of the Cloud signing key in the Gateway service environment:

MESH_EDGE_SIGNING_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----

The private signing key remains in the Cloud service environment and must never be copied to the Gateway or Trade Node host.

Runner Requirements

Kiwi Gateway does not bundle Codex CLI or Claude CLI. Install and authenticate those tools separately, then point the gateway at them when needed:

kwg init --codex-bin codex --claude-bin claude

If Claude is missing, the gateway can still run Codex. If Codex is missing, the gateway starts but the Codex agent is unavailable until the command is installed or CODEX_BIN is configured.

When Gateway and Codex App share the same CODEX_HOME, keep CODEX_BIN on the same Codex CLI version used by the App. The model cache is versioned but shared; an older standalone CLI may fail to deserialize a cache refreshed by a newer App and emit failed to load models cache before otherwise successful tasks. On macOS, pointing CODEX_BIN (or the stable command symlink it references) at /Applications/ChatGPT.app/Contents/Resources/codex keeps both processes on the same cache schema. Alternatively, use separate CODEX_HOME directories.

Development

npm run typecheck
npm test
npm run build
npm run pack:check

Before publishing, inspect the dry-run packlist and verify that no .env, logs, workspaces, tests, source files, backups, or private VPS data are included.

Edge Protocol

The canonical Edge Protocol source is packages/edge-protocol/schema/edge-protocol.source.json. The workspace is versioned and published independently from the Gateway runtime. Generated TypeScript, Python Wheel, JSON Schema, and Protobuf artifacts must share the Digest recorded in packages/edge-protocol/artifact-manifest.json.

npm run protocol:generate
npm run test:edge-protocol
npm publish --workspace @kiwi-mesh/edge-protocol --access public

Do not edit generated protocol artifacts directly or copy Schema sources into consumer repositories.

Runtime Compatibility

Gateway, Mesh, and Trade Node runtime package versions may advance independently. Gateway requires an exact Edge Protocol version for a Trade Node endpoint. An identical protocol artifact Digest is recorded as EXACT. An unknown Digest is rejected even when it is well-formed and has the same protocol version. A future SAME_PROTOCOL Digest must be added to Gateway's internal verified compatibility allowlist only after explicit N/N-1 protocol verification; it cannot be enabled through environment or user configuration. A different protocol version is rejected.

Mesh routing remains capability-based: an endpoint is eligible only when it explicitly advertises the required capability. Gateway advertises mesh-task-skill-v1 in its hello so Mesh can select a runtime that can download, verify, and materialize immutable task Skill snapshots. The runtime package version in General and Trade Critical hellos is read from the installed Gateway manifest.

Publishing to npm

GitHub changes do not automatically update the public npm package. Publish a new npm version only when the change should reach users who install or upgrade @kiwi-mesh/gateway, for example CLI behavior, runtime code, packaged files, or user-facing README changes.

You usually do not need to publish for internal-only notes, tests that do not affect the package, CI-only changes, or experiments that are not ready for users.

Release flow:

git pull --ff-only
npm run typecheck
npm test
npm run build
npm run pack:check

Bump the version before publishing. Use one of these depending on the release size:

npm version patch   # bug fixes and small compatible changes
npm version minor   # new backward-compatible features
npm version major   # breaking changes

Publish the package:

npm publish --access public

Verify the registry and install path:

npm view @kiwi-mesh/gateway version
npm install -g @kiwi-mesh/gateway@latest
kwg version

After publishing, commit and push the version bump if npm version created it locally:

git push origin main --follow-tags

The VPS may have npm auth configured for publishing. Do not commit .npmrc, tokens, .env, generated workspaces, logs, backups, or local databases.