> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/self-hosting/auth-and-network.md).

# Auth & network

How a Telys server decides who may connect — trusted Unix sockets, token-gated TCP with constant-time comparison, the length-prefixed JSON wire protocol, and the offline license gate.

A Telys server has a small, explicit security model: the transport decides trust, an access token gates TCP, an optional license gate blocks boot, and the wire protocol is a length-prefixed JSON frame with a hard size cap. There are no accounts, roles, or per-collection permissions, and the server makes no outbound network calls.

## Transport decides trust

The server authorizes connections by *how* they arrive, not by a per-user identity.

{% tabs %}
{% tab title="Unix socket — trusted" icon="plug" %}
Created with `0600` permissions (owner read/write only) and treated as **trusted**. Any local process that can open the socket file is authorized; no token is required or checked.

Trust here is filesystem trust: the socket-file permissions are the access control. Keep the socket in a directory only trusted users can reach.

```bash
telys serve --path ./memory --socket /run/telys/telys.sock
```

{% endtab %}

{% tab title="TCP — token required" icon="network-wired" %}
Reachable from other hosts, so it is **never** anonymous. Supply an access token when starting the server; a TCP server refuses connections without one, and a client that omits or mismatches the token is rejected.

```bash
telys serve --path ./memory --host 0.0.0.0 --port 9099 \
  --access-token "$TELYS_ACCESS_TOKEN"
```

Bind TCP to a private interface behind a firewall — the token authenticates the caller, it does not encrypt the link.
{% endtab %}
{% endtabs %}

## The token handshake

A client given a token sends an **authentication handshake as its first message**, before any other request. The server compares the presented token against the configured one and either continues or drops the connection.

```python
from telys.client import connect

# token is sent as the first frame, then normal calls follow
with connect("tcp://memory.internal:9099", token="$TELYS_ACCESS_TOKEN") as client:
    print(client.ping())
```

{% hint style="info" %}
The server compares tokens in **constant time**, so a wrong token takes the same time to reject regardless of matching prefix length — closing the timing side-channel a naive equality would open. Generate a long, random token with `secrets.token_urlsafe(32)`, not a memorable phrase.
{% endhint %}

The token is bearer-style — possession is authorization. Treat it like a password: pass it through `$TELYS_ACCESS_TOKEN` rather than a flag to keep it out of shell history and the process list, and rotate it by restarting the server with a new value.

## The license gate

Independently of transport auth, a server can require a valid license before it will run. Start it with `--require-license` (or `require_license=True` in `serve()`), optionally with `--license` / `$TELYS_LICENSE`:

```bash
telys serve --path ./memory --socket /tmp/telys.sock --require-license
```

On boot the server verifies a `products.telys` **version-2** license **entirely offline** — signature and claims are checked against an embedded public key, with no call to a license server. If verification fails, the server refuses to start; there is no unlicensed fallback. This enforces the `telys_team` self-host tier. The verification rules (issuer, audience, expiry, product claims) are in [Offline licenses & verification](https://docs.telys.ai/licensing/offline-licenses.md).

## The wire protocol

Client and server speak a small framed protocol over the socket:

* Each message is a **4-byte length prefix** followed by a **JSON** payload of that many bytes.
* The maximum frame size (`MAX_FRAME`) is **256 MiB**. A frame that declares or exceeds this size is rejected rather than buffered, bounding server memory.

```
+------------------+-------------------------------+
| 4-byte length N  | JSON payload (N bytes)         |
+------------------+-------------------------------+
                    N <= 256 MiB (MAX_FRAME)
```

Framing is identical on both transports; only the socket underneath differs. Requests name a method and its arguments; responses carry the result or an error. Vectors and metadata cross the wire as JSON — batch large ingests into reasonable frames and remember the 256 MiB per-frame ceiling.

## What never happens

{% hint style="success" %}
The server makes **no outbound network calls** of any kind. It listens on the one socket you configured, verifies licenses offline against an embedded key, and reads and writes the store directory — nothing else touches the network. See [What leaves the machine](https://docs.telys.ai/security/what-leaves-the-machine.md) and [On-device & offline-first](https://docs.telys.ai/understand-telys/on-device-offline.md).
{% endhint %}

* No telemetry, phone-home, or usage reporting from the server.
* No online license check — verification is local and offline.
* No per-user identity or role system — trust is transport plus one shared token.

## Next steps

* Next: [Deployment notes](https://docs.telys.ai/self-hosting/deployment.md) — run the server behind a private network, under a supervisor, with backups.
* [Security overview](https://docs.telys.ai/security/overview.md) — how Telys's trust anchors fit together.
* [Connect with RemoteTelys](https://docs.telys.ai/self-hosting/connecting-remote.md) — the client side of this protocol.
