> ## Documentation Index
> Fetch the complete documentation index at: https://docs.synti.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Headless Server

> Run Synti as a token-authenticated WebSocket server for remote, programmatic, and always-on access.

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.

<CodeGroup>
  ```bash Local theme={null}
  export SYNTI_SERVER_TOKEN=$(openssl rand -hex 32)
  synti-cli serve
  ```

  ```bash Remote theme={null}
  export SYNTI_SERVER_TOKEN=$(openssl rand -hex 32)
  export SYNTI_RPC_HOST=0.0.0.0
  synti-cli serve
  ```
</CodeGroup>

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

<Warning>
  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.
</Warning>

## Configuration

The server reads its settings from [environment variables](/reference/config/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

<Steps>
  <Step title="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.
  </Step>

  <Step title="Point the server at them">
    ```bash theme={null}
    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
    ```
  </Step>

  <Step title="Connect over wss://">
    Clients now use a `wss://` URL. For a self-signed certificate, clients must trust your CA with `SYNTI_TLS_CA`.
  </Step>
</Steps>

## Connect a client

<Tabs>
  <Tab title="Terminal (synti-cli)">
    Point the CLI at the server and verify connectivity:

    ```bash theme={null}
    export SYNTI_SERVER_URL=wss://server.example.com:9100
    export SYNTI_SERVER_TOKEN=<token>
    synti-cli ping
    ```

    See [Terminal Client](/server/cli) and the full [CLI reference](/reference/cli).
  </Tab>

  <Tab title="Thin desktop client">
    Launch the desktop app with `SYNTI_SERVER_URL` and `SYNTI_SERVER_TOKEN` set, and it drives the remote server instead of a local one.
  </Tab>

  <Tab title="Browser">
    Open the server's address in a browser and authenticate with the token to use the web UI.
  </Tab>
</Tabs>

## Deployment notes

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="Rotate the token">
    Treat `SYNTI_SERVER_TOKEN` like a password. Rotate it by restarting the server with a new value and updating clients.
  </Accordion>
</AccordionGroup>

## Related

<CardGroup cols={2}>
  <Card title="Terminal Client" icon="terminal" href="/server/cli">
    Connect and drive the server from the shell.
  </Card>

  <Card title="CLI Reference" icon="book" href="/reference/cli">
    Every synti-cli command and flag.
  </Card>

  <Card title="Environment Variables" icon="gear" href="/reference/config/environment-variables">
    All server-mode variables.
  </Card>

  <Card title="Network Proxy" icon="network-wired" href="/reference/config/network-proxy">
    Reach a server through a proxy or CA.
  </Card>
</CardGroup>