Warren Sync

Keep Warren in step across every Mac and share live project views with clients — all hosted on your own server, under your control. Warren Sync is a self-hosted PHP/MySQL server that runs on any shared hosting provider.

🔑

Role required: Admin — Only Admins can configure Warren Sync settings and manage server users.

What Warren Sync gives you

☁️ Automatic sync — Warren pushes a full snapshot after every save and pulls on launch

💻 Multi-device — multiple Macs share the same workspace

🔗 Client share links — password-protected, expirable project URLs on your domain

👥 User management — create accounts, assign roles, reset passwords

📋 Audit log — every sync push/pull, login, and share view is recorded

⚠️

Warren Sync uses a last-write-wins strategy (v1). Warren pushes a full snapshot of its entire DataStore JSON payload to the server after every save. It pulls the latest snapshot on launch. There is no real-time or operational transform — just full serializable state.

Server requirements

The sync server is a self-hosted PHP application. You'll need:

PHP 8.0+ with pdo_mysql, json, and openssl extensions
MySQL 5.7+ or MariaDB 10.3+
Apache with mod_rewrite or Nginx
Any shared host works: Hostinger, SiteGround, Namecheap, DreamHost, etc.

No Composer, no Node, no build tools — just upload and go.

Install the sync server

Create a database

In cPanel / phpMyAdmin (or your host's database tool), run:

CREATE DATABASE warren_sync CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'warren_user'@'localhost' IDENTIFIED BY 'strong_password_here';
GRANT ALL PRIVILEGES ON warren_sync.* TO 'warren_user'@'localhost';
FLUSH PRIVILEGES;

Upload the files

Upload the warren-cloud-sync/ folder to your web server root, e.g. public_html/warren-sync/.

Configure

Duplicate the sample config:

cp config.sample.php config.php

Open config.php and fill in your values:

define('DB_HOST',    'localhost');
define('DB_NAME',    'warren_sync');
define('DB_USER',    'warren_user');
define('DB_PASS',    'strong_password_here');

// Generate a secret: php -r "echo bin2hex(random_bytes(32));"
define('JWT_SECRET', 'paste_64_hex_chars_here');

// The public URL of this folder (no trailing slash)
define('APP_BASE_URL', 'https://yourdomain.com/warren-sync');

// Optional: set your from-address to enable password reset emails
define('MAIL_FROM', 'noreply@yourdomain.com');

Run the installer

Open in your browser:

https://yourdomain.com/warren-sync/install/install.php

The wizard will verify requirements, create database tables, create your admin account, and display your Workspace ID — copy this, you need it in the Warren app.

Secure the installer

Delete or password-protect install/install.php once setup is complete. Leaving it accessible is a security risk.

💡

Nginx? If you're on Nginx instead of Apache, add the configuration from the warren-cloud-sync/README.md to your server {} block.

Connect Warren

Once the server is set up, connect Warren on each Mac:

Open Settings → Warren Sync

Press ⌘, to open Settings, then navigate to Warren Sync.

Enter your server details

Server URL — your APP_BASE_URL (e.g. https://yourdomain.com/warren-sync)
Workspace ID — the UUID from the installer
Email / Password — your Warren Sync admin credentials

Enable sync

Toggle Warren Sync On. Warren will pull the latest snapshot immediately and push automatically after every save.

Multi-device sync

Multiple Macs can push and pull from the same workspace. Each device is identified by its device name and app version. The server keeps a rolling 30-snapshot history per workspace, automatically pruning older snapshots.

Action	What happens
Save in Warren	A full snapshot of your DataStore is pushed to the server immediately.
Launch Warren	Warren pulls the latest snapshot from the server and merges it into the local store.
Snapshot history	The server retains the last 30 snapshots. Older ones are pruned automatically.

⚠️

Conflict resolution: Warren Sync uses a last-write-wins strategy. If two devices make changes independently, the most recent push to the server becomes the authoritative state. To avoid losing work, let one device finish saving before starting work on another.

Share read-only project views with clients via URLs hosted on your own domain. Each link can be password-protected and given an expiry date.

Create a share link

In Warren, open the project you want to share.
Click the Share button (or press ⌘⇧S).
Set an optional password and expiry date.
Click Generate Link and copy the URL to send to your client.

Manage share links

Go to Settings → Warren Sync → Share Links to view, edit, or revoke existing links. Revoked links immediately return a 404 to visitors.

💡

Share links are read-only. Clients can view project progress, phases, and tasks — but cannot edit anything or see internal comments.

User management

Admins can create and manage team members on the sync server. Each user gets their own login and access to shared workspaces.

Roles

Role	Permissions
Admin	Full access: create/edit/delete users, manage workspaces, view audit log, all sync operations.
Member	Push and pull snapshots, create and manage share links for their workspaces.

Create a user

Go to Settings → Warren Sync → Users → click Add User. Enter their name, email, password, and role. They can then log in from any Mac using those credentials.

Reset a password

Admins can force-reset any user's password without knowing the current one. Users can also request a password reset email (valid for 1 hour) or change their own password if they know the current one.

Security

config.php is blocked by .htaccess — it never serves over HTTP
Passwords are hashed with bcrypt (cost factor 10)
JWT tokens use HS256, secrets stored only in config.php
Access tokens expire in 15 minutes; refresh tokens last 30 days and rotate on every use
Password reset tokens expire in 1 hour
Changing a password revokes all existing refresh tokens, forcing re-login on all devices
The includes/ directory is blocked from direct web access

Troubleshooting

Sync isn't working

Check https://yourdomain.com/warren-sync/api/health.php — it should return {"status":"ok"}
Verify your Server URL and Workspace ID in Settings → Warren Sync
Check that your PHP host meets requirements (PHP 8.0+, PDO MySQL extension)
If you changed JWT_SECRET in config.php, all users will need to log in again

Share links return 404

The link may have been revoked — check in Settings → Warren Sync → Share Links
The link may have expired — check the expiry date and recreate if needed
If using Nginx, verify your URL routing configuration matches the README

Forgot admin password

Use the password reset flow: go to the login page → Forgot password? → enter your email → check for a reset link (valid 1 hour). If email isn't configured, an admin with database access can reset it directly in the users table.

← Previous

Integrations

Reports & Insights