Skip to content
by

Docs

First run

The setup page, your owner account, then email and payments.

admin.youragency.com

ClientOS is installed and running. Now you'll finish setup in the browser, then connect email and payments, in that order. Plan on 30 to 60 minutes, most of it spent in the Resend dashboard.

A fresh install has no staff accounts. The defaults it seeds are your workspace, order statuses, roles and a starter price book, but no people. Your owner account is created on the setup page below.

Finish setup in the browser#

Below, YOUR_ADMIN is your team's address and YOUR_PORTAL your clients', the two you chose while installing (for example team.youragency.com and clients.youragency.com).

Your browser moves to the setup page by itself once the installer has connected your addresses. It is:

https://YOUR_ADMIN/setup

Until setup is finished, every page of the portal and admin sends you there, so https://YOUR_ADMIN works too. The first visit can take a minute while Caddy gets the HTTPS certificates.

If the page doesn't open or shows a certificate warning, DNS isn't pointing at the server yet. See Troubleshooting.

The setup key#

The setup page first asks for a setup key. It stops a stranger who finds your fresh install from claiming it before you do. The installer printed it at the end, and you can show it again on the server at any time:

sudo clientos setup-key

Too many wrong attempts lock the form for a few minutes. Once setup is finished, the key no longer matters.

Walk through the steps#

Everything except the license and your account can be changed later in Settings.

  1. Welcome. Paste your setup key, then click Get started.
  2. License. The key you gave the installer is already here, so press Next. ClientOS asks Vibemonk to bind it to your domain, and Vibemonk checks that your domain reaches this server over HTTPS, which can take a few seconds. To use a different key, paste it instead.
  3. Your agency. Enter your Agency name, Website, Support email and Business address. These are the contact details your clients see.
  4. Region. Choose your Currency (what you invoice in) and Timezone (whose calendar dates follow).
  5. Brand. Pick a Primary color (headings, the sidebar and quiet accents) and an Accent color (buttons, links and anything clickable).
  6. Your account. Enter Your name, Your email and a Password (at least 12 characters), then confirm it. This becomes the owner account, with full access.
  7. Review. Check everything, use Edit on any section to go back, then click Finish setup.

You'll see Your workspace is ready and be signed in as the owner. The finish screen lists your next steps. The rest of this page covers each one.

Once anyone on your team has signed in, setup closes for good and /setup sends people to the sign-in page instead.

If the license step fails#

The message says why. The usual causes:

  • The domain doesn't reach this server over HTTPS yet. Wait for DNS and the certificate, then press Next again.
  • The key is active on another domain. Release it from your account at vibemonk.com, under Licenses, or from Settings → License on the old install.
  • The key was mistyped or revoked. Copy it again from your account.

You can check the license later at Settings → License. See Your license.

Alternative: create the owner from the command line#

If you'd rather not use a browser, you can create the owner with a command on the server, from the deploy folder of your install:

cd /path/to/clientos/deploy
sudo docker compose exec api \
  node dist/modules/auth/bootstrap-owner.cli.js --email [email protected] --name "Your Name"

What to know about the command:

  • It prints a generated password once, to your terminal and nowhere else. Copy it straight away.
  • It refuses to run once any staff member has signed in, so it can't be used as a back door later.

Then sign in at https://YOUR_ADMIN with that email and password, go to Settings → License and activate your key (the admin is read-only until you do), and change the password in step 6 below.

After setup: connect everything, in this order#

ClientOS sends email only through your Resend account. There's no fallback: until you connect it, sign-in codes, invitations and notifications can't be sent. Connect it first.

1. Connect Resend#

  1. In Resend, add your sending domain (for example youragency.com or mail.youragency.com) and add the SPF and DKIM records it gives you at your DNS provider. Wait until Resend shows the domain as verified.
  2. In Resend, go to API Keys and create a key. A Full access key lets ClientOS check your domains and register its delivery webhook for you. A sending-only key also works, and ClientOS tells you what it couldn't check.
  3. In the admin, go to Settings → Integrations → Resend, paste the key (it starts with re_) and save.
  4. Wait until the status shows connected. If it shows needs attention, follow what it says. Usually the domain isn't verified yet, or the sender you set in the next step isn't on a verified domain.

When the key allows it, connecting also registers Resend's delivery webhook at https://YOUR_PORTAL/v1/mail/webhooks/resend, so bounces and complaints are tracked automatically. If it can't, the dialog asks for the signing secret of a webhook you add in Resend yourself.

2. Set up Emails and send a test#

  1. Go to Settings → Emails.
  2. Enter the sender name and a sender address on the domain you verified in Resend. Optionally add a reply-to address.
  3. Click Send test and check that it arrives in your own inbox.

You can also choose which notifications are emailed here, and edit every email's wording under Settings → Email templates. See Notifications and email.

3. Check file storage#

Files already work: the installer set up storage on your server, at YOUR_PORTAL/clientos-media. Go to Settings → Company and upload your logo. If it appears on the sign-in page, storage works end to end.

Files on your server are included in clientos backup. If you'd rather keep them in Cloudflare R2, see Moving files to Cloudflare R2 below. It's best decided now, before anything is uploaded.

4. Connect Cloudflare Turnstile#

Optional, but recommended. Turnstile protects your public pages, such as signup and free checkouts, from bots.

  1. In the Cloudflare dashboard, open Turnstile and add a widget. Add your portal address, for example YOUR_PORTAL.
  2. Copy the site key and secret key.
  3. In the admin, go to Settings → Integrations → Turnstile and paste both.

5. Connect payment gateways, test keys first#

  1. Go to Settings → Integrations and connect your gateway: Stripe, PayPal, NOWPayments, CoinGate or BTCPay Server.
  2. Start with test or sandbox keys. ClientOS detects whether a key is test or live, and registers the gateway's webhook at https://YOUR_PORTAL/v1/payments/webhooks/... for you where the provider allows it. The gateway card tells you if it couldn't.
  3. Use Verify on the gateway card to confirm the connection.
  4. Make a test purchase: open one of your services at https://YOUR_PORTAL/services/... and pay. With Stripe test keys, use the card 4242 4242 4242 4242. Check that the order appears, its receipt invoice is paid, and the gateway card shows the webhook arriving.
  5. Only then switch to live keys with Replace keys, and repeat with a small real payment that you refund.

Also review Settings → Payments: your currency, tax rate and tax name, processing fee, manual crypto wallets, dunning and renewal reminders. See Checkout and payments.

6. Secure your account#

Turn on two-factor authentication for your own account at Settings → Security. You can require it for the whole team later. See Team and permissions.

If you created the owner from the command line, change the generated password there too.

7. Schedule backups#

Run one backup by hand, then schedule a daily one:

sudo clientos backup
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 backups folder off the server regularly. See Backups.

8. Invite your team and import clients#

Only now, with email working, should you bring other people in. An invitation sent before email works never arrives.

  • Team: go to Team and invite each person by email with the role they need. See Team and permissions.
  • Clients: add clients one at a time from Clients, or import a CSV file with Import from a file on the Clients page. Adding a client invites them to sign in with an emailed code. See Clients and companies.

Moving files to Cloudflare R2#

Optional. By default every file (logos, deliverables, attachments, receipts and invoice PDFs) is stored on your server. To keep them in a Cloudflare R2 bucket instead:

In Cloudflare:

  1. Open R2 in the Cloudflare dashboard and create a bucket, for example clientos-files.
  2. Copy your Account ID from the R2 overview sidebar.
  3. Go to Manage API tokens → Create API token. Choose the permission Object Read & Write and scope it to that one bucket only. Copy the Access Key ID and Secret Access Key.
  4. Optional: on the bucket's Settings tab, attach a custom domain or turn on the r2.dev subdomain. This is the public URL for your logos. If you skip it, ClientOS serves logos through the API instead, which works everywhere and is a little slower.

In the admin:

  1. Go to Settings → Storage.
  2. Enter the Account ID, Bucket name, Jurisdiction (leave it on the default unless you created the bucket in a specific jurisdiction), Access key ID, Secret access key and, if you set one up, the Public URL.
  3. Save. ClientOS runs connection checks against the bucket and refuses keys the bucket rejects. You can rerun them any time with Run checks.
  4. Copy the CORS policy shown on the page and paste it into Cloudflare under R2 → your bucket → Settings → CORS policy. Browser uploads fail without it, and it's the one thing the checks can't test for you.

From the moment you save, every file is read from R2. Files already uploaded to your server must be copied into the bucket first, with any S3 copy tool such as rclone or mc mirror. That's why it's easiest to decide before anything is uploaded.

Once files are in R2, clientos backup no longer covers them. Back the bucket up separately; see Backups.

Checklist#

  • Finished the setup page, and the license step shows Licensed
  • Verified your sending domain in Resend
  • Connected Resend at Settings → Integrations, status connected
  • Set the sender at Settings → Emails, and the test email arrived
  • Uploaded your logo at Settings → Company, and it shows on the sign-in page
  • Connected Turnstile
  • Connected a payment gateway with test keys and made a successful test purchase
  • Switched to live keys and tested with a small refunded payment
  • Turned on two-factor authentication
  • Set MAIL_POSTAL_ADDRESS in deploy/.env (see Configuration)
  • Scheduled clientos backup, and copied a backup off the server
  • Invited your team
  • Imported or invited your clients

Next, set up your branding and your first services: Branding and white-label and Services and the store.