> 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

Run a Telys server durably in production — private networking, systemd or supervisor management, auto-restart, timed saves, and store backups on the self-host Team tier.

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](https://docs.telys.ai/licensing/tiers-and-pricing.md) and [Offline licenses & verification](https://docs.telys.ai/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](https://docs.telys.ai/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](https://docs.telys.ai/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](https://docs.telys.ai/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](https://docs.telys.ai/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="https://docs.telys.ai/self-hosting/overview.md">Overview</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="https://docs.telys.ai/licensing/tiers-and-pricing.md">Plans &amp; licensing</a></td></tr><tr><td><strong>Auth &#x26; network model</strong></td><td>Trust, tokens, and the wire protocol.</td><td><a href="https://docs.telys.ai/self-hosting/auth-and-network.md">Auth &amp; network</a></td></tr></tbody></table>
