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

npm install -g @kiwi-mesh/gateway

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

One-command Start

npm install -g @kiwi-mesh/gateway && 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

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 restarts once per failed check, stores consecutive failure state in ~/.kiwi-gateway/watchdog-state.json, and writes a critical log only after three consecutive failed recovery attempts.

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 "$(command -v kwg)"
launchctl print "gui/$(id -u)/com.kiwi.gateway"

# 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.

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.

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.

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.