Headless Server

The Synti server runs the agent without a desktop window, exposing it over a WebSocket that clients connect to. Use it to keep an agent running on a remote machine, drive it from CI, or share one backend across the terminal client, a browser, and thin desktop clients. Clients authenticate with a bearer token, and remote deployments should always run over TLS.

Start a server

Generate a token and launch the server. Bind to loopback for local-only use, or to all interfaces for remote access.

export SYNTI_SERVER_TOKEN=$(openssl rand -hex 32)
synti-cli serve

export SYNTI_SERVER_TOKEN=$(openssl rand -hex 32)
export SYNTI_RPC_HOST=0.0.0.0
synti-cli serve

The server listens on 127.0.0.1:9100 by default. Print the token you generated and keep it safe — clients need it verbatim.

Never expose the server on a network without TLS. Anyone who can reach the port and token gets full agent access, including tools that run commands and read files.

Configuration

The server reads its settings from environment variables.

Setting	Variable	Default
Auth token (required)	`SYNTI_SERVER_TOKEN`	—
Bind address	`SYNTI_RPC_HOST`	`127.0.0.1`
Port	`SYNTI_RPC_PORT`	`9100`
TLS certificate	`SYNTI_RPC_TLS_CERT`	—
TLS private key	`SYNTI_RPC_TLS_KEY`	—
TLS CA chain	`SYNTI_RPC_TLS_CA`	—

When a certificate and key are set, the server accepts secure wss:// connections; otherwise it speaks plain ws://.

Enable TLS

Obtain a certificate and key

Use a trusted certificate (for example from Let’s Encrypt) for public hosts, or a self-signed pair for private networks.

Point the server at them

export SYNTI_RPC_TLS_CERT=/etc/synti/server.crt
export SYNTI_RPC_TLS_KEY=/etc/synti/server.key
export SYNTI_RPC_HOST=0.0.0.0
synti-cli serve

Connect over wss://

Clients now use a wss:// URL. For a self-signed certificate, clients must trust your CA with SYNTI_TLS_CA.

Connect a client

Terminal (synti-cli)
Thin desktop client
Browser

Point the CLI at the server and verify connectivity:

export SYNTI_SERVER_URL=wss://server.example.com:9100
export SYNTI_SERVER_TOKEN=<token>
synti-cli ping

See Terminal Client and the full CLI reference.

Launch the desktop app with SYNTI_SERVER_URL and SYNTI_SERVER_TOKEN set, and it drives the remote server instead of a local one.

Deployment notes

Put TLS termination at a reverse proxy

For production, front the server with nginx, Caddy, or a Cloudflare Tunnel and let it handle TLS. The server can then bind to loopback while the proxy faces the network.

Prefer a private network

Tailscale, a WireGuard mesh, or an SSH tunnel keeps the server off the public internet entirely while still allowing remote clients.

Rotate the token

Treat SYNTI_SERVER_TOKEN like a password. Rotate it by restarting the server with a new value and updating clients.

Terminal Client

Connect and drive the server from the shell.

CLI Reference

Every synti-cli command and flag.

Environment Variables

All server-mode variables.

Network Proxy

Reach a server through a proxy or CA.

​Start a server

​Configuration

​Enable TLS

​Connect a client

​Deployment notes

​Related

Terminal Client

CLI Reference

Environment Variables

Network Proxy

Start a server

Configuration

Enable TLS

Connect a client

Deployment notes

Related