--- title: Headless server description: 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-.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](https://github.com/Emanuele-web04/synara/releases) and download `synara-server-.tar.gz` for the exact Synara version you intend to run. ### Extract it into a dedicated directory ```bash 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 ```bash npm install --omit=dev ``` Keep the generated dependency directory beside the extracted `package.json` and `dist/` tree. ### Start loopback-only first ```bash 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: ```bash 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: ```bash 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: ```bash 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`. 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](/docs/workflows/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 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