> 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

Serve a collection directory over a socket so other processes — local or across the network — can reach it with [`connect` / `RemoteTelys`](/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: choose a transport: --socket, or both --host and --port  (exit 2)

telys serve --path ./memory --host 0.0.0.0 --port 8899
# error: TCP requires --access-token (anonymous TCP is refused)  (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`, `build_ivf`, `snapshot`, `tune`, and `apply_tuning` are local-only. See the [Remote API](/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](/self-hosting/running-a-server.md) — the guided walkthrough.
* [Connect with RemoteTelys](/self-hosting/connecting-remote.md) — the client side.
* [Auth & network model](/self-hosting/auth-and-network.md) — trusted sockets vs. authenticated TCP.
* [Remote API (connect / RemoteTelys)](/reference/remote-api.md) — the client SDK surface.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/cli/serve.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.