---
title: 'Install on Linux'
url: 'https://chronoslice.app/docs/installing/install-on-linux'
markdown: 'https://chronoslice.app/docs/installing/install-on-linux.md'
date: '2026-11-14'
description: 'This page covers everything up to a running server: the download, a system user, the data folder, the settings file and a systemd service. It assumes a Debian or Ubuntu style server where you can run commands with sudo. For a Mac or Docker, see Install on macOS and Run with Docker. HTTPS and the fi…'
taxonomy:
  kb_category:
    - Installing
---

[Docs](https://chronoslice.app/docs)

 [Contact support](https://chronoslice.app/help/new) 

Docs menu

# Install on Linux

Put the ChronoSlice binary on a Linux server, give it a user, a data folder and a settings file, and run it with systemd.

 Updated Nov 14, 2026 4 min read

This page covers everything up to a running server: the download, a system user, the data folder, the settings file and a systemd service. It assumes a Debian or Ubuntu style server where you can run commands with `sudo`. For a Mac or Docker, see [Install on macOS](https://chronoslice.app/docs/installing/install-on-macos) and [Run with Docker](https://chronoslice.app/docs/installing/run-with-docker). HTTPS and the first account come next, in [Reverse proxy and HTTPS](https://chronoslice.app/docs/installing/reverse-proxy-and-https) and [The first account](https://chronoslice.app/docs/installing/the-first-account).

## Get the files

1. Open [the download page](https://chronoslice.app/download). The trial build is the same download as the licensed one. If you've bought a licence, the same files are on your account's Licenses page.
2. Download the Linux build that matches your server. Run `uname -m` on the server to check. `x86_64` is the x86\_64 build, and `aarch64` is the arm64 build. The file is named `chronoslice-<version>-linux-x86_64.tar.gz` or `chronoslice-<version>-linux-arm64.tar.gz`.
3. Copy it to the server and unpack it. The archive holds one folder with `chronoslice` (the program), `INSTALL.md`, `LICENSE` and `THIRD-PARTY-NOTICES.txt`.

```sh
tar -xzf chronoslice-0.1.0-linux-x86_64.tar.gz
sudo install -m 755 chronoslice-0.1.0-linux-x86_64/chronoslice /usr/local/bin/chronoslice
chronoslice --version
```

Use your own version number in the file names. The last command prints the version and its release date, such as `chronoslice 0.1.0 (released 2026-11-12)`.

> \[!NOTE\] Keep the program at `/usr/local/bin/chronoslice`. The rest of these docs, including `sudo chronoslice update`, assume that path.

## Make a user and the folders

ChronoSlice runs as its own system user, `chronoslice`, and keeps its data in `/var/lib/chronoslice`. Its settings go in `/etc/chronoslice`.

```sh
sudo useradd --system --home /var/lib/chronoslice --shell /usr/sbin/nologin chronoslice
sudo mkdir -p /var/lib/chronoslice /etc/chronoslice
sudo chown chronoslice:chronoslice /var/lib/chronoslice
```

## Write the settings file

The settings file is `/etc/chronoslice/env`. It holds `KEY=value` lines, and systemd reads it when it starts the service. Create it with your editor, for example `sudo nano /etc/chronoslice/env`:

```ini
CHRONOSLICE_DB=sqlite:///var/lib/chronoslice/chronoslice.db
CHRONOSLICE_BIND=127.0.0.1:7340
CHRONOSLICE_PUBLIC_URL=https://time.example.com
CHRONOSLICE_SECURE_COOKIES=true
CHRONOSLICE_SETUP_TOKEN=paste-a-long-random-string-here
```

- `CHRONOSLICE_DB` is the database. The three slashes after `sqlite:` are right: they are the two from `sqlite://` and the one that starts the path. The server creates the file on first start.
- `CHRONOSLICE_BIND` is where ChronoSlice listens. Keep it on `127.0.0.1` so only your reverse proxy can reach it.
- `CHRONOSLICE_PUBLIC_URL` is the address people use, with no path. Emails link to invoices with it, and Stripe sends clients back to it after they pay.
- `CHRONOSLICE_SECURE_COOKIES=true` marks the sign-in cookie Secure. Set it once HTTPS works. The value must be `true` or `false`.
- `CHRONOSLICE_SETUP_TOKEN` is a secret that the first-run setup page asks for, so nobody else can create the first account. Make one with `openssl rand -hex 24`. See [The first account](https://chronoslice.app/docs/installing/the-first-account).

Email settings go in the same file. See [Email](https://chronoslice.app/docs/installing/email). Every setting is listed in [Settings reference](https://chronoslice.app/docs/installing/settings-reference).

Then lock the file down. It can hold your SMTP password, so only root should read it:

```sh
sudo chmod 600 /etc/chronoslice/env
```

## Run it with systemd

Create `/etc/systemd/system/chronoslice.service`:

```ini
[Unit]
Description=ChronoSlice
After=network-online.target
Wants=network-online.target

[Service]
User=chronoslice
Group=chronoslice
EnvironmentFile=/etc/chronoslice/env
ExecStart=/usr/local/bin/chronoslice serve
WorkingDirectory=/var/lib/chronoslice
Restart=on-failure
NoNewPrivileges=true
ProtectSystem=strict
ProtectHome=true
PrivateTmp=true
ReadWritePaths=/var/lib/chronoslice

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

The service can write only to `/var/lib/chronoslice`. If you point email at a `file://` folder for testing, or keep backups somewhere else, add that folder to `ReadWritePaths`.

Start it:

```sh
sudo systemctl daemon-reload
sudo systemctl enable --now chronoslice
```

## Check that it's running

Watch the log:

```sh
journalctl -u chronoslice -f
```

You should see `listening on http://127.0.0.1:7340`. On a new install the log also says that there are no accounts yet and where to finish setup. If email isn't set up, it says `email is off`. That's expected until you add the email settings.

Ask the server directly:

```sh
curl -s http://127.0.0.1:7340/api/setup
```

A new install answers `{"needed":true,"token_required":true}`, which means it's waiting for its first account and wants the setup token.

## What the server does by itself

- The database is created on first start, and its structure is brought up to date every time the server starts.
- Every hour, and once at start, the server makes recurring invoices that are due, retries recurring invoices whose email failed, sends reminders and block alerts, and checks open Stripe payments.
- Which day it is, for recurring invoices, issue dates and reminders, comes from the organization's timezone. See [Organization settings](https://chronoslice.app/docs/using-chronoslice/clients-projects-tasks-and-tags).

## Next

Put a reverse proxy in front of the server: [Reverse proxy and HTTPS](https://chronoslice.app/docs/installing/reverse-proxy-and-https).

## Related

- [The first account](https://chronoslice.app/docs/installing/the-first-account)
- [From Toggl Track](https://chronoslice.app/docs/moving-to-chronoslice/from-toggl-track)

## Still stuck?

Send us a request: it goes to the people who build ChronoSlice, and the reply comes by email. Include your ChronoSlice version (Settings › Licence shows it) and what you tried.

 [Contact support](https://chronoslice.app/help/new?from=%2Fdocs%2Finstalling%2Finstall-on-linux)[Your requests](https://chronoslice.app/help/tickets)

---

## Navigation

- Parent: [Installing](https://chronoslice.app/docs/installing.md)
- Next: [Install on macOS](https://chronoslice.app/docs/installing/install-on-macos.md)
