> 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/running-a-server.md).

# Run a server

Start a long-lived Telys server on a Unix socket or an access-token-protected TCP port, from the CLI or from Python, with durability and supervision options.

A Telys server is one process that owns a store directory and answers client requests over a socket. Start it with `telys serve` or the equivalent `serve()` function from `telys.server`. Either call **blocks**: it runs in the foreground until stopped, which is what you want under a process manager.

{% hint style="warning" %}
Point exactly one server at a given `--path`. The server is the single writer; running two servers against the same path — or reading the files while a server owns them — corrupts on-disk state. Serving is the `telys_team` tier; sign in accordingly. See [Plans & licensing](https://docs.telys.ai/licensing/tiers-and-pricing.md).
{% endhint %}

## Prerequisites

* Telys installed and the runtime verified: `telys runtime verify`. See [Verify your install](https://docs.telys.ai/start-here/verify-install.md).
* A store directory. It is created if absent; pass an existing one to serve collections you already have.

## Start on a Unix socket (trusted, local)

Use a Unix domain socket when every client runs on the same host. The socket file is created with `0600` permissions and treated as trusted, so no token is needed.

{% stepper %}
{% step %}

#### Run the server

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

{% endstep %}

{% step %}

#### Confirm it is listening

The process holds the foreground and the socket file appears:

```bash
ls -l /tmp/telys.sock
```

```
srw------- 1 you staff 0 Jul 14 14:20 /tmp/telys.sock
```

The leading `s` and the `rw-------` mode confirm a Unix socket you own with `0600` permissions.
{% endstep %}
{% endstepper %}

## Start on a TCP port (token required)

To reach the server from another host, listen on TCP. TCP **requires** an access token — the server refuses anonymous connections. Generate a strong token, pass it once, and bind to a private interface.

```bash
export TELYS_ACCESS_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
telys serve \
  --path ./memory \
  --host 0.0.0.0 --port 9099 \
  --access-token "$TELYS_ACCESS_TOKEN"
```

`--access-token` reads `$TELYS_ACCESS_TOKEN` when the flag is omitted, keeping the secret out of shell history and the process list.

{% hint style="danger" %}
Serving on `0.0.0.0` exposes the port on every interface. Restrict it to a private network with a firewall or bind to a specific internal address; never expose a Telys server to the public internet. See [Auth & network model](https://docs.telys.ai/self-hosting/auth-and-network.md).
{% endhint %}

## Useful flags

Pass either `--socket` or both `--host` and `--port`; supplying neither exits with code `2`. The rest are optional.

| Flag                      | Purpose                                                                       |
| ------------------------- | ----------------------------------------------------------------------------- |
| `--path PATH`             | Store directory the server owns (required).                                   |
| `--socket SOCKET`         | Listen on a Unix socket at this path.                                         |
| `--host HOST --port PORT` | Listen on TCP (both required together).                                       |
| `--access-token TOKEN`    | Bearer token for TCP; falls back to `$TELYS_ACCESS_TOKEN`. Required for TCP.  |
| `--license LICENSE`       | License token; falls back to `$TELYS_LICENSE`.                                |
| `--require-license`       | Verify a `products.telys` license offline on boot; refuse to start otherwise. |
| `--save-interval SECONDS` | Periodically persist open collections (default `0.0` = off).                  |
| `--supervise`             | Restart the worker automatically if it exits.                                 |

### Durability with `--save-interval`

Collections persist when a client calls `save()`. Set `--save-interval` to also flush open collections on a timer, bounding how much recent work a crash could lose:

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

### Auto-restart with `--supervise`

`--supervise` restarts the worker if it crashes. It complements an external process manager but does not replace one; see [Deployment notes](https://docs.telys.ai/self-hosting/deployment.md).

```bash
telys serve --path ./memory --host 127.0.0.1 --port 9099 \
  --access-token "$TELYS_ACCESS_TOKEN" --require-license --supervise
```

### Require a license on boot

```bash
export TELYS_LICENSE="$TELYS_LICENSE"
telys serve --path ./memory --socket /tmp/telys.sock --require-license
```

With `--require-license`, the server verifies a `products.telys` version-2 license entirely offline before accepting a single connection. See [Offline licenses & verification](https://docs.telys.ai/licensing/offline-licenses.md).

## Start from Python

`serve()` is the same server behind the CLI. It blocks, so run it as your process entry point. Pass a Unix `socket_path`, or `host` and `port` as keyword arguments.

{% code title="run\_server.py" %}

```python
from telys.server import serve

# Unix socket (trusted, local)
serve("./memory", socket_path="/tmp/telys.sock", save_interval_s=30.0)

# TCP (token required) — this form instead of the line above:
# serve(
#     "./memory",
#     host="0.0.0.0",
#     port=9099,
#     access_token="$TELYS_ACCESS_TOKEN",
#     require_license=True,
# )
```

{% endcode %}

The full signature is `serve(path, socket_path=None, *, host=None, port=None, license_token=None, require_license=False, access_token=None, embedder_factory=None, save_interval_s=0.0)`. On boot the server best-effort pre-registers `AlgentaBigramEmbedder` as `"bigram"`; pass an `embedder_factory` to expose other embedders to remote `create_collection` calls by name.

## Expected result

A running server prints nothing on success and holds the foreground:

* **Unix socket:** the socket file exists at your `--socket` path with mode `srw-------` (`0600`).
* **TCP:** the port is open on your chosen host, e.g. `nc -z 127.0.0.1 9099` returns success.

From a second terminal, a client handshake and `ping()` confirm end to end:

```python
from telys.client import connect

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

```
True
[]
```

An empty `collections()` list is expected for a fresh store — only *saved* collections appear. Stop the server with Ctrl-C.

## Next steps

* Next: [Connect with RemoteTelys](https://docs.telys.ai/self-hosting/connecting-remote.md) — create and query collections against this server.
* [Auth & network model](https://docs.telys.ai/self-hosting/auth-and-network.md) — how the token check and wire protocol work.
* [Deployment notes](https://docs.telys.ai/self-hosting/deployment.md) — run it under systemd or a supervisor with backups.
