craby-gateway

CLI package for running the Craby desktop gateway service.

Install

npm install -g craby-gateway

Requires Node 20 or newer.

First-time setup now writes a user config file at ~/.craby-ai/gateway.yaml.

Publish

Set your npmjs access token in the repo root .npmrc file. A checked-in example lives at .npmrc.example, while .npmrc is gitignored:

cp .npmrc.example .npmrc

Then edit .npmrc and set:

//registry.npmjs.org/:_authToken=npm_xxxxxxxxxxxxxxxxxxxx

Build and inspect the package contents before publishing:

pnpm --filter @remote-agent/desktop-gateway run pack:check

Publish from the workspace package:

pnpm --filter @remote-agent/desktop-gateway run publish:npm

Useful verification commands:

npm whoami --userconfig ../../.npmrc
npm view craby-gateway version

Run

Initialize the user config, inspect local provider versions, then start the gateway:

craby-gateway init
craby-gateway doctor
craby-gateway start

craby-gateway start also auto-creates ~/.craby-ai/gateway.yaml if it does not exist yet.

By default start prints a short startup summary to the terminal and writes detailed runtime logs to ~/.craby-ai/logs/gateway.log. Add --log to mirror runtime logs to the console too:

craby-gateway start --log

The generated YAML is grouped by concern instead of keeping everything flat:

configVersion: 1
gateway:
  host: 0.0.0.0
  port: 8787
  httpsEnabled: false
  httpsPort: 8787
  apiKey: ...
  accessSecret: ...
  refreshSecret: ...
  enableNativeProviders: true
  requireNativeCodex: false
  workspaceRoot: ~/...
  auditLogPath: ~/.craby-ai/logs/audit.log
  gatewayLogPath: ~/.craby-ai/logs/gateway.log
  idleTtlMs: 900000

Default config values include:

• httpsEnabled: false
• port: 8787
• generated apiKey, accessSecret, and refreshSecret
• enableNativeProviders: true
• detailed runtime logs at ~/.craby-ai/logs/gateway.log

Older flat config files are still accepted for compatibility.

The doctor command checks:

• whether the user's machine exposes a working codex --version command
• the bundled @anthropic-ai/claude-agent-sdk version installed with the package
• the user's machine claude --version output when that command exists

The package still accepts environment variable overrides. Common ones include:

• GATEWAY_HOST
• GATEWAY_PORT
• GATEWAY_HTTPS_ENABLED
• GATEWAY_HTTPS_PORT
• GATEWAY_WORKSPACE_ROOT
• ENABLE_NATIVE_PROVIDERS
• REQUIRE_NATIVE_CODEX
• GATEWAY_BOOTSTRAP_PAIRING_CODE_ON_START

You can also point commands at a custom config file:

craby-gateway doctor --config /path/to/gateway.yaml
craby-gateway start --config /path/to/gateway.yaml --log

Notes

• The published package ships a bundled, minified gateway entrypoint.
• yaml, qrcode-terminal, and pino are bundled into the published CLI package.
• The published gateway does not install @openai/codex; Codex execution relies on the user's system codex command or REMOTE_AGENT_CODEX_BIN.
• @anthropic-ai/claude-agent-sdk stays as a runtime dependency because native Claude integration still loads it dynamically.