---
title: 'Install on macOS'
url: 'https://chronoslice.app/docs/installing/install-on-macos'
markdown: 'https://chronoslice.app/docs/installing/install-on-macos.md'
date: '2026-11-14'
description: 'This page covers everything up to a running server on a Mac: the download, a data folder, the settings file and a launchd daemon that starts at boot and restarts if it stops. It suits a Mac that stays on, such as a Mac mini in the office. For a server on the internet, a Linux VPS is usually the bet…'
taxonomy:
  kb_category:
    - Installing
---

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

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

Docs menu

# Install on macOS

Put the ChronoSlice binary on a Mac that stays on, give it a data folder and a settings file, and run it as a launchd daemon.

 Updated Nov 14, 2026 7 min read

This page covers everything up to a running server on a Mac: the download, a data folder, the settings file and a launchd daemon that starts at boot and restarts if it stops. It suits a Mac that stays on, such as a Mac mini in the office. For a server on the internet, a Linux VPS is usually the better home. See [Install on Linux](https://chronoslice.app/docs/installing/install-on-linux). 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).

The macOS build is universal, so one download runs on Apple silicon and Intel Macs. It's signed and notarized, and it runs on macOS 11 (Big Sur) or later. This is the server. The Mac app is a separate download that needs macOS 26.

## Get the files

1. Open [the download page](https://chronoslice.app/download) and download the macOS server build. 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. The file is named `chronoslice-<version>-macos-universal.tar.gz`. The archive holds one folder with `chronoslice` (the program), `dev.chronoslice.server.plist` (the launchd file used below), `INSTALL.md`, `LICENSE` and `THIRD-PARTY-NOTICES.txt`.
3. Unpack it and put the program in `/usr/local/bin`:

```sh
tar -xzf chronoslice-0.1.0-macos-universal.tar.gz
cd chronoslice-0.1.0-macos-universal
sudo mkdir -p /usr/local/bin
sudo install -m 755 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 launchd file below and `sudo chronoslice update` assume that path. The first time a downloaded copy runs, macOS checks its notarization with Apple, so the Mac needs a network connection then.

## Make the folders

The daemon runs as an ordinary account on the Mac, yours or one made for it. launchd starts ChronoSlice as that account, so the account owns the data folder, the log file and, in the next step, the settings file. ChronoSlice keeps its data in `/usr/local/var/chronoslice`, its log in `/usr/local/var/log/chronoslice.log` and its settings in `/etc/chronoslice`.

```sh
sudo mkdir -p /usr/local/var/chronoslice /usr/local/var/log /etc/chronoslice
sudo touch /usr/local/var/log/chronoslice.log
sudo chown "$USER" /usr/local/var/chronoslice /usr/local/var/log/chronoslice.log
```

These commands use your own account. For an account made for ChronoSlice, put its name in place of `"$USER"` here, in the settings step and in the launchd file.

## Write the settings file

The settings file is `/etc/chronoslice/env`. It holds `KEY=value` lines. ChronoSlice reads it itself when it starts, and so does every `chronoslice` command you run, so they all find the same database. Unlike on Linux, where systemd reads the file as root and hands the settings over, nothing reads it for ChronoSlice here, so the daemon's account has to be able to read it. Create it with your editor, for example `sudo nano /etc/chronoslice/env`:

```ini
CHRONOSLICE_DB=sqlite:///usr/local/var/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 the daemon's account should read it (root still can, for `sudo chronoslice update`):

```sh
sudo chown "$USER" /etc/chronoslice/env
sudo chmod 600 /etc/chronoslice/env
```

### Using it only on your own network

If you only want ChronoSlice on your own network, without HTTPS, set these instead of the address and cookie lines:

```ini
CHRONOSLICE_BIND=0.0.0.0:7340
CHRONOSLICE_PUBLIC_URL=http://your-mac.local:7340
```

Leave out `CHRONOSLICE_SECURE_COOKIES`, because a browser won't keep a Secure cookie from an `http://` address. Replace `your-mac` with the Mac's name. Passkeys need HTTPS, so without it people sign in with a password and an authenticator app or an emailed code. The Mac app accepts a plain `http://` address for a name ending in `.local`.

## Run it as a daemon

`dev.chronoslice.server.plist` is in the download. Open it and set `UserName` to the account that owns `/usr/local/var/chronoslice`. The file runs `/usr/local/bin/chronoslice serve`, starts it at boot, keeps it running, and writes its log to `/usr/local/var/log/chronoslice.log`.

Install it and start it:

```sh
sudo cp dev.chronoslice.server.plist /Library/LaunchDaemons/
sudo chown root:wheel /Library/LaunchDaemons/dev.chronoslice.server.plist
sudo launchctl bootstrap system /Library/LaunchDaemons/dev.chronoslice.server.plist
```

To stop it, run `sudo launchctl bootout system/dev.chronoslice.server`. To restart it after changing `/etc/chronoslice/env`, run `sudo launchctl kickstart -k system/dev.chronoslice.server`.

## Check that it's running

Watch the log:

```sh
tail -f /usr/local/var/log/chronoslice.log
```

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.

If it doesn't start:

- **No log at all,** and `sudo launchctl print system/dev.chronoslice.server` shows `last exit code = 78: EX_CONFIG`: launchd couldn't open the log file as the daemon's account. Check that the account owns `/usr/local/var/log/chronoslice.log`, then run `sudo launchctl kickstart -k system/dev.chronoslice.server`.
- **`"token_required":false`** even though you set a token, or the log says `can't read the settings in /etc/chronoslice/env`: the daemon's account can't read the settings file. Run the `chown` from the settings step, then restart it the same way.

The database is created on first start, and its structure is brought up to date every time the server starts.

## HTTPS and the first account

For a public address, put a reverse proxy in front of the server. Caddy works well on a Mac (`brew install caddy`), with the same Caddyfile as in [Reverse proxy and HTTPS](https://chronoslice.app/docs/installing/reverse-proxy-and-https). A Cloudflare Tunnel (`cloudflared`) also works, and needs no open ports on your router.

Then open the public address. A new install shows the setup page, which asks for your name, email and password, then your organization. See [The first account](https://chronoslice.app/docs/installing/the-first-account). Until that's done, anyone who can reach the server could make the first account, so finish it right after the first start, or set `CHRONOSLICE_SETUP_TOKEN` first as above.

## Updating and backups

`sudo chronoslice update` downloads the newest release your licence covers, backs up the database, swaps the program and restarts the daemon. See [Updating](https://chronoslice.app/docs/licence-and-updates/updating).

The database is the one file `/usr/local/var/chronoslice/chronoslice.db`. Time Machine copies it, but a copy taken while the server is writing can be inconsistent, so also take a clean one on a schedule. This makes a consistent copy while the server runs, and the file name must be new. Run it as the daemon's account, which can read the settings and so finds the database:

```sh
chronoslice backup /path/to/backups/chronoslice-$(date +%F).db
```

Litestream (`brew install litestream`) can stream the database to S3-compatible storage, as it does on Linux. See [Backups and restoring](https://chronoslice.app/docs/installing/backups-and-restoring).

## Uninstalling

If you entered a licence key, take it off this server first, so its seat is free for another one:

```sh
chronoslice licence remove
```

Keep a last copy of the database, unless you're sure you won't want it again:

```sh
chronoslice backup ~/chronoslice-final.db
```

Then stop the daemon and remove the program, its settings, its data and its log:

```sh
sudo launchctl bootout system/dev.chronoslice.server
sudo rm /Library/LaunchDaemons/dev.chronoslice.server.plist
sudo rm -f /usr/local/bin/chronoslice /usr/local/bin/chronoslice.previous
sudo rm -rf /etc/chronoslice /usr/local/var/chronoslice
sudo rm -f /usr/local/var/log/chronoslice.log
sudo rmdir /usr/local/var/log /usr/local/var
```

The last line removes the two folders only when nothing else is in them. If another program uses them, `rmdir` says `Directory not empty` and leaves them alone, which is what you want. If you set up Caddy or a Cloudflare Tunnel for ChronoSlice, remove its entry there too. The Mac app is separate: quit it and drag it from Applications to the Trash.

## Next

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

## Related

- [The first account](https://chronoslice.app/docs/installing/the-first-account)
- [Quick start](https://chronoslice.app/docs/getting-started/quick-start)
- [Requirements](https://chronoslice.app/docs/getting-started/requirements)

## 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-macos)[Your requests](https://chronoslice.app/help/tickets)

---

## Navigation

- Parent: [Installing](https://chronoslice.app/docs/installing.md)
- Previous: [Install on Linux](https://chronoslice.app/docs/installing/install-on-linux.md)
- Next: [Run with Docker](https://chronoslice.app/docs/installing/run-with-docker.md)
