@meego-harness/gateway

Node-only gateway package for Meego harness.

What it does

• creates and owns a MeegoHarnessSDK
• creates and owns the embedded worker server
• serves the dashboard UI, REST API, and SSE stream
• optionally starts an ngrok tunnel
• exposes loadOrBootstrapGatewayServerConfig() as the main programmatic helper for persisted config.json startup
• keeps resolveGatewayServerConfigFromEnv() as a lower-level helper for programmatic callers that still need to map env manually

Install

pnpm add @meego-harness/gateway

CLI

The package ships with an official CLI for running or managing a single gateway instance:

pnpm exec meego-harness-gateway run --host 0.0.0.0 --port 3000
pnpm exec meego-harness-gateway start
pnpm exec meego-harness-gateway stop
pnpm exec meego-harness-gateway status
pnpm exec meego-harness-gateway autostart enable
pnpm exec meego-harness-gateway autostart disable

Behavior:

• the CLI reads ~/.meego-harness/gateway/config.json by default
• if the config file does not exist yet, the CLI creates a setup-mode draft config
• --host <host> writes gateway.host into config.json before running or starting the service
• --port <number> writes gateway.port into config.json before running or starting the service
• start, stop, and autostart manage the user-level service through LaunchAgent on macOS or systemd user service on Linux
• when the gateway is started from a bound config file, the dashboard Gateway Config page reads and writes that full JSON
• saving config only updates config.json; restart the gateway process to apply the new values

You can also point it at another config location:

pnpm exec meego-harness-gateway run --config-file ./gateway.config.json --host 0.0.0.0 --port 4100

Programmatic startup

If you start the gateway through code instead of the CLI, prefer the persisted config helper rather than reading env directly:

import {
  GatewayServer,
  loadOrBootstrapGatewayServerConfig,
} from '@meego-harness/gateway'

const { config } = loadOrBootstrapGatewayServerConfig({
  env: process.env,
  configFile: './gateway.config.json',
})

const gateway = new GatewayServer(config)
await gateway.start()

Behavior:

• the helper reads config.json when it already exists
• it bootstraps from env only when that config file does not exist yet
• callers can pass a custom configFile path explicitly

Manager-agent runtime

When a workspace enables managerAgent, the gateway starts the manager-agent in-process. If a model is configured, the gateway also starts a dedicated LLM worker for that manager-agent. Remote manager clients are not part of this runtime.

For environment variables, use the repository root .env.example as the single source of truth.

Notes:

• manager-agent LLM workers use the same worker authorization flow as other workers
• MEEGO_HARNESS_MANAGER_OPENAPI_WHITELIST is read directly by the embedded MeegoHarnessSDK
• if the whitelist is unset or [], managers can still use worker/task/HITL/event admin APIs, but invokeOpenApi() is denied

Upload Worker Credentials

Gateway stores workspace-level credentials and sends task-level leases to workers that have been bound to those credentials. Supported kinds currently include lark-cli and bytedcli.

Steps:

1. Complete lark-cli login on the machine where you will run the upload command.
2. Open the Gateway dashboard and select the target workspace.
3. Open 集成入口 -> 访问令牌, create a workspace OpenAPI token, and copy it.
4. Upload the credential:

MEEGO_HARNESS_TOKEN=<gateway-token> npx @meego-harness/credential upload lark-cli \
  --gateway http://127.0.0.1:3000 \
  --workspace workspace-alpha \
  --name "Lark CLI" \
  --user-email [email protected]

Parameters:

• MEEGO_HARNESS_TOKEN: Gateway workspace OpenAPI token.
• --gateway: Gateway base URL, without /api.
• --workspace: Gateway workspace key.
• --name: credential display name.
• --user-email: optional account email for display, filtering, and audit. If omitted, the CLI tries to detect it from local lark-cli credentials.
• --source-dir <dir>: optional local config or data directory to read credential material from.
• --application-support-dir <dir>: optional paired application support directory when uploading from custom local paths.
• --config-dir <dir>: optional paired config directory for bytedcli when uploading from a custom data directory.

After upload, open the top-level Credentials tab in Gateway and check the matching credential kind sub tab. Then open the worker detail page and bind the credential. One credential can be bound to multiple workers.

Workers can also declare expectedCredentialKinds, such as ['lark-cli'], in their worker login payload. When such a worker receives a task, Gateway attempts to auto-bind one matching owner-only credential with the same email and kind before creating the task lease. If no match exists, task dispatch still continues without a credential lease.