> 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 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](/licensing/tiers-and-pricing.md). {% endhint %} ## Prerequisites * Telys installed and the runtime verified: `telys runtime verify`. See [Verify your install](/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](/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](/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](/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](/self-hosting/connecting-remote.md) — create and query collections against this server. * [Auth & network model](/self-hosting/auth-and-network.md) — how the token check and wire protocol work. * [Deployment notes](/self-hosting/deployment.md) — run it under systemd or a supervisor with backups. --- # 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/self-hosting/running-a-server.md?ask=&goal= ``` `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.