Docs Contact support
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 and the first account come next, in Reverse proxy and HTTPS and 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 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:
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.

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:

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.

Email settings go in the same file. See Email. Every setting is listed in 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):

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:

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:

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:

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:

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. 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. 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.

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:

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.

Uninstalling

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

chronoslice licence remove

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

chronoslice backup ~/chronoslice-final.db

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

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. Then create your account: The first account.

Was this helpful?

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.