Headless server

Install Zyron’s release tarball, run the web workspace without Electron, verify readiness, and expose it remotely only with deliberate authentication and transport controls.

Zyron releases include zyron-server-<version>.tar.gz for running the same local server and web client without the Electron desktop shell. Use it for a supervised local service, a dedicated development machine, or an environment where the desktop package is not appropriate.

The tarball is not a single static binary. It contains the built application, package metadata, and the source-shipped iOS device helper; install its production Node dependencies before starting it.

Requirements

  • Node.js 22.19 or newer in the supported engine range
  • npm for installing the production dependencies
  • At least one supported provider CLI installed and authenticated for the service account
  • A private directory for Zyron state

Provider credentials and model access still belong to the provider runtime. Running the headless package does not create a Zyron-hosted account or move provider authentication into the tarball.

Install the release tarball

Download the matching release asset

Open the official GitHub release and download zyron-server-<version>.tar.gz for the exact Zyron version you intend to run.

Extract it into a dedicated directory

mkdir zyron-server
tar -xzf zyron-server-0.7.3.tar.gz -C zyron-server
cd zyron-server

The extracted root contains only dist/ and package.json.

Install production dependencies

npm install --omit=dev

Keep the generated dependency directory beside the extracted package.json and dist/ tree.

Start loopback-only first

node dist/index.mjs --no-browser --home-dir /absolute/path/to/zyron-data

Zyron binds to 127.0.0.1 unless you explicitly choose a different host. The data directory stores server state separately from the extracted application, which makes replacing the release files safer.

Check server readiness

From the extracted directory, probe the runtime associated with the same data directory:

node dist/index.mjs server status --home-dir /absolute/path/to/zyron-data

The status command discovers the persisted runtime origin, verifies that it is the Zyron process recorded for that data directory, calls /health, and reports whether startup and projection are ready. It exits non-zero when discovery, identity verification, reachability, or readiness fails.

For machine-readable output:

node dist/index.mjs server status --home-dir /absolute/path/to/zyron-data --json

To probe a specific HTTP(S) origin instead of discovering one:

node dist/index.mjs server status --url "$ZYRON_SERVER_ORIGIN" --json

An explicit URL must use HTTP or HTTPS and cannot contain embedded credentials.

Choose the data directory deliberately

Pass --home-dir consistently to the server, status checks, and any External MCP bridge. Different data directories are different Zyron installations: they have separate projects, tasks, settings, runtime identity, and integration credentials.

Do not point two live Zyron servers at the same data directory. Do not store the data directory inside a repository an agent can rewrite.

Remote access is opt-in

The safe default is loopback-only. Binding a wildcard or non-loopback address requires an authentication token and one of these explicit transport decisions:

  • Set --public-url "$ZYRON_PUBLIC_URL" to an HTTPS origin when a trusted reverse proxy terminates TLS.
  • Set --allow-insecure-remote only for an authenticated connection on a trusted private network where plaintext transport is a deliberate risk acceptance.

Prefer service-manager environment variables for secrets instead of placing a token in shell history. The corresponding variables are ZYRON_AUTH_TOKEN, ZYRON_PUBLIC_URL, ZYRON_HOST, and ZYRON_ALLOW_INSECURE_REMOTE.

Remote access disables Zyron’s loopback-only External MCP HTTP endpoint. External MCP clients should normally remain local and use their paired stdio launcher; see External MCP.

Updating a headless installation

  1. Preserve important repository work and stop active provider turns.
  2. Stop the existing server process.
  3. Back up the configured data directory before an early-release migration.
  4. Extract the new release into a fresh application directory.
  5. Run npm install --omit=dev in that directory.
  6. Start it with the same --home-dir and access policy.
  7. Run server status and complete one small task before removing the previous application directory.

Do not overwrite the state directory with files from the tarball. Application files and Zyron data have separate lifecycles.

Completion checklist

  • The tarball came from the official release and matches the intended version
  • Production dependencies installed successfully
  • The server started with a dedicated absolute data directory
  • server status reported ready
  • Provider CLIs are available to the service account
  • Remote binding, authentication, and TLS policy are explicit
  • Important state is backed up before an update
  • A real task was verified after installation or upgrade

Last updated on