Install guide
What self-hosting actually involves
A summary of the real work, in order, so you can judge it before you buy anything. The official documentation is the authority and every section below links to the page it summarises — this page exists to show you the shape of the job, including the parts that are work.
1. A server
Any Linux VPS with a public IPv4 address. A fresh one is best, and it must not already be running nginx or Apache, because ClientOS brings its own web server and needs ports 80 and 443. The docs name Hetzner, DigitalOcean, Vultr, Linode and AWS Lightsail; any provider works.
| Resource | Minimum | Recommended |
|---|---|---|
| Operating system | Ubuntu 22.04 or Debian 12 | Ubuntu 24.04 LTS |
| CPU | 1 vCPU | 2 vCPU |
| Memory | 2 GB | 4 GB |
| Free disk | 10 GB | 20 GB or more, SSD |
| Network | Public IPv4, ports 80 and 443 open | — |
2. One DNS record, added first
ClientOS runs on one domain — say clients.youragency.com — with
the client portal at /, the admin at /admin and the API at
/v1. It needs a single A record pointing that name at your
server’s IP address.
Type Name Value TTL
A clients 203.0.113.5 Auto (or 300)Three things the docs are specific about, each of which will otherwise cost you an hour:
- Add it before you install. The installer checks the record against public DNS and against your actual server before it downloads anything.
- On Cloudflare, set it to DNS only — the grey cloud. Let’s Encrypt has to reach your server directly for the first certificate, and the orange-cloud proxy blocks that. You can turn the proxy on afterwards.
- Delete a stale AAAA record on that name unless it is your server’s own IPv6 address. Let’s Encrypt tries IPv6 first, and a wrong AAAA record stops the certificate.
The domain has to be public, must not already be serving a website, and your licence binds to it — a key can change domain three times in its life, so pick the one you mean to keep.
3. One command
Your licence page at vibemonk.com gives you an install command with your key already in it. SSH into the server, paste it, press enter.
$ ssh root@YOUR_SERVER_IP
$ curl -fsSL https://license.vibemonk.com/v1/licensing/install/clientos \
| sudo bash -s -- --license-key CLOS-XXXX-XXXX-XXXX-XXXXIt checks your key, downloads the installer and verifies its fingerprint, unpacks it to
/opt/clientos, installs Docker if it is missing, adds swap on a small server,
and writes your configuration with freshly generated passwords. Then it prints a link to
finish in the browser.
If you would rather not pipe a script into bash, the same installer is downloadable as a
.tar.gz from your licence page — upload it, unpack it, run
sudo ./install.sh --license-key …. Both paths run exactly the same checks. For a
provisioning script, add --domain, --email and --yes to
skip the browser step without skipping the checks.
One constraint worth knowing early: ClientOS installs only on a server your domain reaches over the internet. Before anything downloads, the licence server checks from outside that your domain answers on that machine — so a laptop, a home network or an unpointed domain cannot install it.
4. Finish in the browser
Open the link the terminal printed, enter your domain and an email address for certificate renewal warnings, and press Connect. The licence server verifies your domain from the internet and binds your key to it; only then is ClientOS downloaded, with every file checked against its fingerprint. HTTPS takes a minute or two, then your browser moves on to the setup page by itself.
The setup page at /admin/setup is guarded by a setup key the
installer printed — it stops a stranger who finds your fresh server from claiming it first.
If you lose it, sudo clientos setup-key shows it again. Seven steps: welcome,
licence, your agency, region (currency and timezone), two brand colours, your owner account
(password at least 12 characters), review. About two minutes.
5. Connect email, then everything else
This is where the time actually goes. The docs put first run at 20 to 40 minutes, most of it spent in your email provider’s dashboard adding SPF and DKIM records, and they give the order for a reason:
- 01
Email, first
Resend, or any SMTP server — Google Workspace, Microsoft 365, Zoho, Amazon SES. There is no fallback: until one is connected, sign-in codes, invitations and notifications cannot be sent.
- 02
Sender and a test
Set the sender name and an address on the domain you verified, then send a test to your own inbox before you trust it.
- 03
File storage
Already working on your server. If you would rather keep files in a Cloudflare R2 bucket, decide now — before anything is uploaded — because existing files have to be copied over by hand.
- 04
Turnstile
Optional but recommended. Cloudflare Turnstile protects your public signup and free checkout pages from bots.
- 05
Payments, test keys first
Connect Stripe, PayPal, NOWPayments, CoinGate or BTCPay Server with test keys, make a test purchase, confirm the order and the webhook arrived — then switch to live keys and repeat with a small real payment you refund.
- 06
Two-factor, then your team
Turn on 2FA for your own account. Only then invite anyone: an invitation sent before email works never arrives.
6. Backups — the part you have to do yourself
If you read one section of this page, read this one. ClientOS gives you a one-command backup, but the docs are explicit that nothing runs it until you schedule it.
$ sudo clientos backup
# writes three files into backups/ and keeps the newest seven of each:
# db-DATE.dump your whole database
# files-DATE.tar.gz every file stored on the server
# env-DATE deploy/.env, including CREDENTIAL_SECRET
# then schedule it — daily at 03:00:
$ echo '0 3 * * * root /usr/local/bin/clientos backup >/var/log/clientos-backup.log 2>&1' \
| sudo tee /etc/cron.d/clientos-backup- Copy the folder off the server. A backup on the same disk is lost with the
disk. Another server, your own machine, or a bucket via rclone — and keep the copies
private, because the
envfiles hold your secrets. - Restore one before your first real client goes in, and again every few months. The docs put it well: a backup you have never restored is a hope, not a backup.
- Check that recent files exist. A backup job that silently stopped weeks ago is the most common failure.
- If you move files to Cloudflare R2,
clientos backupno longer covers them and the bucket needs backing up separately.
Living with it: the clientos command
| Command | What it does |
|---|---|
clientos status | The version, what is running and whether it is healthy |
clientos update | Takes a backup, downloads the newest release your licence covers, restarts. Migrations run before the new API starts |
clientos rollback | Back to the release before the last update, once |
clientos backup | Database, files and settings into backups/ |
clientos restore FILE… | Puts a backup back; asks you to type restore to confirm |
clientos logs [service] | Follows the logs, of everything or one service |
clientos domain NEW | Moves ClientOS, and your licence, to another domain |
clientos setup-key | Shows the setup page’s key again |
Updates also run from the admin at Settings → License → Updates, and the docs note that the
admin never gets root access for this — it leaves a request that a small service on the
server picks up. A release that changes existing data will say so in its notes and wants
clientos update --stop-first, which costs about a minute of downtime instead of
the old version writing old-style data into the new database.
Point an uptime monitor at https://YOUR_DOMAIN/v1/health: it returns 200 with
PostgreSQL and Redis reported, and 503 when the database cannot be reached. Docker restarts a
container whose process crashes, but not one that is running and unhealthy.
Install questions
What do I need to run it?
A Linux VPS with 2 to 4 GB of RAM running Ubuntu 22.04 or 24.04 or Debian 12, a domain you can add one A record to, your licence key, and an email account to send from — Resend or your own SMTP server. One command installs everything else, including Docker, PostgreSQL, file storage and HTTPS.
How long does installing it take?
The docs put the install at about 10 minutes — one command, then connecting your domain in the browser — and the setup page that follows at about two minutes. Allow 20 to 40 minutes in total for first run, because most of that time is spent in your email provider’s dashboard adding SPF and DKIM records.
I am not technical. Can someone set it up for me?
Yes. Installing is one command, but on the Premium and Custom packages the ClientOS team installs it on your server, connects email and payments, and hands over a working portal.
What happens if my server cannot reach the licence server?
ClientOS keeps working and your team sees a warning saying when the grace period ends, which is seven days after the last successful check-in. After that — or immediately if the key is revoked or released — the admin becomes read-only. The client portal keeps working, checkout and webhooks keep working, and nothing is deleted.
Do backups happen automatically?
No, and this is worth knowing before you go live. One command — clientos backup — writes the database, your files and your settings into a folder, but the docs are explicit that nothing runs it for you until you schedule it. They give a cron line for a daily 03:00 backup and tell you to copy the folder off the server.
This page is a summary, written 29 October 2026. The official ClientOS documentation is the authority and is kept current — follow it, not this, when you actually install. If the two ever disagree, the docs are right and this page is out of date; tell us in a GitHub issue and we will fix it.
Or skip the server and just look at it
The instant demo emails you a login to a live, fully installed ClientOS with sample clients, orders and invoices. Read-only, 3 days, no call and no card.