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

Synara releases include synara-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 Synara state

Provider credentials and model access still belong to the provider runtime. Running the headless package does not create a Synara-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 synara-server-<version>.tar.gz for the exact Synara version you intend to run.

Extract it into a dedicated directory

mkdir synara-server
tar -xzf synara-server-0.7.3.tar.gz -C synara-server
cd synara-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/synara-data

Synara 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/synara-data

The status command discovers the persisted runtime origin, verifies that it is the Synara 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/synara-data --json

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

node dist/index.mjs server status --url "$SYNARA_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 Synara installations: they have separate projects, tasks, settings, runtime identity, and integration credentials.

Do not point two live Synara 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 "$SYNARA_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 SYNARA_AUTH_TOKEN, SYNARA_PUBLIC_URL, SYNARA_HOST, and SYNARA_ALLOW_INSECURE_REMOTE.

Do not publish the raw server port

A successful loopback launch is not permission to forward the port to the internet. Configure authentication and trusted TLS termination before changing the bind host.

Remote access disables Synara’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

Preserve important repository work and stop active provider turns.
Stop the existing server process.
Back up the configured data directory before an early-release migration.
Extract the new release into a fresh application directory.
Run npm install --omit=dev in that directory.
Start it with the same --home-dir and access policy.
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 Synara 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

Headless server