> 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/cli/serve.md).

# telys serve

Reference for telys serve — expose a collection path over a trusted Unix socket or an authenticated TCP endpoint for RemoteTelys clients.

Serve a collection directory over a socket so other processes — local or across the network — can reach it with [`connect` / `RemoteTelys`](https://docs.telys.ai/reference/remote-api.md). `serve` blocks, running in the foreground until interrupted. The server makes no outbound network calls.

## Synopsis

```
telys serve --path PATH (--socket SOCKET | --host HOST --port PORT)
            [--access-token TOKEN] [--license LICENSE] [--require-license]
            [--save-interval SECONDS] [--supervise]
```

Choose a transport: `--socket` (Unix domain socket) or both `--host` and `--port` (TCP). Providing neither is a usage error and exits `2`.

## Options

| Flag                | Value   | Default               | Meaning                                                                               |
| ------------------- | ------- | --------------------- | ------------------------------------------------------------------------------------- |
| `--path`            | dir     | (required)            | Collection directory to serve.                                                        |
| `--socket`          | path    | (none)                | Serve over a Unix domain socket at this path.                                         |
| `--host`            | host    | (none)                | TCP bind host. Requires `--port` and `--access-token`.                                |
| `--port`            | int     | (none)                | TCP bind port. Requires `--host`.                                                     |
| `--access-token`    | token   | `$TELYS_ACCESS_TOKEN` | Bearer token clients must present. **Required for TCP.**                              |
| `--license`         | token   | `$TELYS_LICENSE`      | License token to verify when `--require-license` is set.                              |
| `--require-license` | flag    | off                   | Verify a `products.telys` (ver 2) license offline on boot; refuse to start otherwise. |
| `--save-interval`   | seconds | `0.0`                 | Periodically persist the collection. `0.0` disables the timer.                        |
| `--supervise`       | flag    | off                   | Run the server under a supervisor that keeps it alive.                                |

## Transports

{% tabs %}
{% tab title="Unix socket" icon="plug" %}
The Unix socket is created with mode `0600` and treated as trusted: any local process that can open it is allowed, so no token is required.

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

Connect from a client:

```python
from telys.client import connect

with connect("unix:///tmp/telys.sock") as db:
    print(db.ping())
```

{% endtab %}

{% tab title="TCP" icon="network-wired" %}
TCP is never anonymous: pass an access token, or the server refuses to start a TCP listener. The token is compared in constant time.

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

Connect with the same token:

```python
from telys.client import connect

with connect("tcp://memory.internal:8899", token="$TELYS_ACCESS_TOKEN") as db:
    print(db.ping())
```

{% endtab %}
{% endtabs %}

## Usage errors

`serve` exits `2` for a malformed invocation:

```bash
telys serve --path ./memory
# error: pass --socket <path> (Unix) or --host <h> --port <p> (TCP)  (exit 2)

telys serve --path ./memory --host 0.0.0.0 --port 8899
# error: TCP serving requires access_token= (no anonymous network access)  (exit 2)
```

## Licenses and persistence

* **`--require-license`** verifies a `products.telys` license (schema version 2) offline before the server starts. Pass the token with `--license` or `$TELYS_LICENSE`; if it does not verify, the server refuses to boot.
* **`--save-interval`** persists the served collection on a timer. The default `0.0` disables periodic saves; clients can still persist explicitly.

The server pre-registers `AlgentaBigramEmbedder` under the model id `bigram` on a best-effort basis, so text ingestion and text search work out of the box when the native kernel is present.

{% hint style="warning" %}
The wire protocol frames are length-prefixed JSON with a maximum frame of 256 MiB. `RemoteCollection` exposes a subset of the local `Collection` API: remote `search` has no `target_recall`, and `update_texts`, `tune`, and `apply_tuning` are local-only. See the [Remote API](https://docs.telys.ai/reference/remote-api.md).
{% endhint %}

## Exit codes

| Code | Meaning                                                            |
| ---- | ------------------------------------------------------------------ |
| `0`  | Server ran and shut down cleanly.                                  |
| `1`  | Runtime not available, or license verification failed.             |
| `2`  | Usage error (no transport chosen, or TCP without an access token). |

## See also

* [Run a Telys server](https://docs.telys.ai/self-hosting/running-a-server.md) — the guided walkthrough.
* [Connect with RemoteTelys](https://docs.telys.ai/self-hosting/connecting-remote.md) — the client side.
* [Auth & network model](https://docs.telys.ai/self-hosting/auth-and-network.md) — trusted sockets vs. authenticated TCP.
* [Remote API (connect / RemoteTelys)](https://docs.telys.ai/reference/remote-api.md) — the client SDK surface.
