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

# Deployment

A Telys server is a single long-lived process that owns one store directory and answers clients over a socket. Deploying it is ordinary service hygiene: keep it on a private network, run it under a process manager, persist on a timer, and back up the store. These practices apply to the `telys_team` self-host tier.

{% hint style="info" %}
Serving is the `telys_team` tier. Start the server with `--require-license` so it verifies a `products.telys` license offline on boot and refuses to run without one. See [Plans & licensing](/licensing/tiers-and-pricing.md) and [Offline licenses & verification](/licensing/offline-licenses.md).
{% endhint %}

## Network placement

* **Prefer a Unix socket** when clients share the host. It is trusted (`0600`) and needs no token — the simplest and safest option. See [Auth & network model](/self-hosting/auth-and-network.md).
* **For cross-host access, use TCP with an access token on a private network.** Bind to an internal interface, restrict the port with a firewall or security group, and never expose the server to the public internet. The token authenticates callers but does not encrypt traffic.
* The server makes **no outbound connections**, so egress can stay closed. Only inbound access to your chosen socket or port is required.

## Run under a process manager

Because `telys serve` blocks in the foreground, it slots into systemd, a container entrypoint, or a supervisor. Add `--supervise` so the server restarts its worker automatically if it exits; the process manager restarts the whole unit if the process itself dies.

{% tabs %}
{% tab title="systemd" icon="linux" %}
Keep the token out of the unit file by loading it from a `0600` environment file.

{% code title="/etc/telys/telys.env" %}

```bash
TELYS_ACCESS_TOKEN=replace-with-a-long-random-token
TELYS_LICENSE=your-products-telys-license-jwt
```

{% endcode %}

{% code title="/etc/systemd/system/telys.service" %}

```ini
[Unit]
Description=Telys memory server
After=network-online.target

[Service]
Type=simple
User=telys
EnvironmentFile=/etc/telys/telys.env
ExecStart=/usr/local/bin/telys serve \
  --path /var/lib/telys/memory \
  --host 127.0.0.1 --port 9099 \
  --require-license \
  --save-interval 30 \
  --supervise
Restart=on-failure
RestartSec=2

[Install]
WantedBy=multi-user.target
```

{% endcode %}

```bash
systemctl daemon-reload
systemctl enable --now telys.service
systemctl status telys.service
```

`--access-token` and `--license` fall back to `$TELYS_ACCESS_TOKEN` and `$TELYS_LICENSE`, which the `EnvironmentFile` supplies.
{% endtab %}

{% tab title="supervisor" icon="gear" %}
{% code title="/etc/supervisor/conf.d/telys.conf" %}

```ini
[program:telys]
command=/usr/local/bin/telys serve --path /var/lib/telys/memory --socket /run/telys/telys.sock --save-interval 30 --supervise
autostart=true
autorestart=true
startsecs=3
user=telys
environment=TELYS_LICENSE="%(ENV_TELYS_LICENSE)s"
```

{% endcode %}

```bash
supervisorctl reread
supervisorctl update
supervisorctl status telys
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
Run **exactly one** server per store directory. The server is the single writer; a second server on the same `--path`, or any process reading the collection files while the server owns them, corrupts on-disk state. To scale reads, point more clients at the one server, not more servers.
{% endhint %}

## Durability

By default a collection persists only when a client calls `save()`. In a shared deployment, set `--save-interval` so the server also flushes open collections on a timer, bounding how much recent work an unclean shutdown could lose:

```bash
telys serve --path /var/lib/telys/memory --socket /run/telys/telys.sock --save-interval 30
```

A save writes the `id_map.npy` sidecar first and `collection.json` last as the commit point, so a partial save is detectable rather than silently corrupt. Clients can still call `save()` after important batches; the interval is a floor. See [Snapshots & persistence](/working-with-data/snapshots-and-persistence.md).

## Backups

Everything a collection needs lives in files under the store directory — `collection.json` (the commit point), the `id_map.npy` sidecar, and the runtime vector slab files. Back up the **store directory** and you back up the collections. See [On-disk layout](/operations/on-disk-layout.md) for what each file is.

{% stepper %}
{% step %}

#### Reach a consistent point

Take the backup when the store is not mid-write: stop the unit briefly, use a filesystem or volume snapshot, or copy right after a `--save-interval` flush. `collection.json` present and newest indicates a committed collection.
{% endstep %}

{% step %}

#### Copy the store directory

```bash
systemctl stop telys.service
tar -czf telys-backup-$(date +%F).tgz -C /var/lib/telys memory
systemctl start telys.service
```

{% endstep %}

{% step %}

#### Restore by unpacking to a fresh path

```bash
tar -xzf telys-backup-2026-07-14.tgz -C /var/lib/telys-restore
telys serve --path /var/lib/telys-restore/memory --socket /run/telys/telys.sock
```

Point a server at the restored directory and connect to verify with `client.collections()` and `col.stats()`.
{% endstep %}
{% endstepper %}

## Upgrades

Upgrade the server the same way you upgrade Telys anywhere: install the new version, then restart the service. Stop the unit, upgrade, run `telys runtime verify`, and start it again. The on-disk `FORMAT_VERSION` is stable within a release line; keep a backup from before the upgrade. See [Upgrade Telys](/operations/upgrading.md).

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Serving overview</strong></td><td>When and why to run Telys as a server.</td><td><a href="/pages/GRqsH5DPQpYEB3ISZf53">/pages/GRqsH5DPQpYEB3ISZf53</a></td></tr><tr><td><strong>Tiers &#x26; pricing</strong></td><td>The telys_team self-host tier and what it includes.</td><td><a href="/pages/hGLr4vJ3ScfwXbJDIcyi">/pages/hGLr4vJ3ScfwXbJDIcyi</a></td></tr><tr><td><strong>Auth &#x26; network model</strong></td><td>Trust, tokens, and the wire protocol.</td><td><a href="/pages/N6BRLlIY4N7N32k9EspF">/pages/N6BRLlIY4N7N32k9EspF</a></td></tr></tbody></table>


---

# 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/deployment.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.