Environment and troubleshooting

Variables read when starting the Host

These apply when running npx vibex or npx vibex serve.

VIBEX_HOST_FAMILY_TAG: GitHub Release tag to download. Default is v plus the CLI version, for example v0.1.3. Pin a Host build so scripts keep a matching binary.

VIBEX_HOST_FAMILY_BASE: URL prefix for the tarball. Default https://github.com/Xircth/VibeX/releases/download/<tag>. An internal mirror places the full archive on its own HTTP directory and sets this.

VIBEX_HOST_FAMILY_DIR: already extracted family directory (must contain SHA256SUMS, vibex-server, web/). When set, download is skipped.

VIBEX_GITHUB_REPO: GitHub owner/name, default Xircth/VibeX.

VIBEX_STATIC_ROOT: Web UI static file root. npx vibex points it at packaged web/. When you start vibex-server yourself and need the browser UI, point this at a web/ tree.

VIBEX_SERVER_ALLOW_LAN: set to 1 and even npx vibex (loopback start) listens on every NIC. npx vibex serve --local on the command line still binds loopback only.

VIBEX_SERVER_LISTEN: a port number such as 18080, or ip:port. Overrides the default 17891. Command-line --port also overrides the default port.

VIBEX_SERVER_TOKEN: Host token used at start. When non-empty, the saved token in the data directory is ignored.

VIBEX_DEBUG: any non-empty value prints a JavaScript stack on CLI failure.

VIBEX_DATA_DIR: Host data directory. npx vibex serve, npx vibex list, and npx vibex install share this SQLite. Unset, the machine default data directory is used.

Variables read by control commands

VIBEX_URL: Host root URL, default http://127.0.0.1:17891. A trailing / is stripped. Change this after a port change or an HTTPS reverse proxy.

VIBEX_TOKEN: Bearer token, required. Missing it raises VIBEX_TOKEN is required. Copy it from the Token block of npx vibex serve, or from desktop Settings → Remote connection.

Control commands also accept --json, --operation-id, and --timeout. See Control-plane conventions.

Common failures

Unsupported platform: this OS/CPU pair is outside the six published combinations (linux/mac/windows × x64/arm64). Use a supported machine, or open GitHub Releases and confirm that platform’s archive.

Host family download failed: network, firewall, or a bad tag. Check VIBEX_HOST_FAMILY_TAG and open the Release page for vibex-host-family-<platform>.tar.gz.

Checksum mismatch: a corrupt cache or a truncated download. Delete ~/.vibex/host-family/<tag>/ and retry, or point at a verified VIBEX_HOST_FAMILY_DIR.

Host family is missing vibex-server: the extracted tree is incomplete. Download again; copy the full archive, not a subset of files.

VIBEX_TOKEN is required: the token is unset. Run npx vibex serve and copy from the terminal, or copy from the desktop remote-connection page.

Timed out after Ns: the turn or workflow was still non-terminal. Raise --timeout, or inspect with npx vibex conversation show / npx vibex workflow show.

Missing required --x: a required flag is absent. Compare with npx vibex help conversation (or the matching resource).

Plugin validation failed: the plugin pack failed validation. Fix by the printed code, see Package layout, then run npx vibex plugin pack again.

Port in use: switch to npx vibex serve --port 18080, or stop the process holding 17891.

pass --yes to install without a prompt: npx vibex install ran without a terminal and without --yes. Use npx vibex install AGENT_ID --yes.

npm was not found / uv was not found: the local installer needs Node/npm or uv already on this machine. Install the toolchain, then run npx vibex install. Full write-up: Install Agents locally.

npx vibex help
npx vibex --version