Team Template

Requires Extended Subscription

Team Template requires an active Extended Subscription.

Overview

Team Template lets a team share a curated Gridmux profile. A manager sets up a starting-point profile — workspaces, layouts, aliases, notes — and publishes it to a shared remote. Team members consume that profile and receive updates over time.

Team Template and Cloud Sync are two modes of the same sync engine. Team Template is the team mode (with roles); Cloud Sync is the single-user, cross-device mode.

What gets synced

Gridmux syncs a fixed set of five profile files (the “bundle”):

• aliases.json — aliases
• settings.json — settings
• session.json — workspaces and layouts
• recents.json — recent projects
• team-notes.json — notes

Only these files are synced — project files and Git repositories are never touched.

Roles

Each device picks a role:

• Manager — can push and pull; sees a Publish team template update button to push the shared profile.
• Peer — can push and pull (no manager button).
• Subscriber — pull-only; pushing is blocked in the UI and the engine.

Note

Roles are advisory — a convenience guard against accidental pushes. The real access boundary is your remote’s permissions (Git repository permissions or R2 bucket policies). Set those up so a subscriber genuinely can’t write.

Providers

You can store the bundle on either:

• Git — a repository (repo URL + branch), authenticated with a Personal Access Token. The repo URL must be HTTPS (SSH is not supported).
• Cloudflare R2 — an S3-compatible bucket (endpoint + bucket + access key + secret key).

Credentials are kept in your operating system’s keychain — never written to settings.json or a repo’s .git/config.

Setting it up

Open Settings → Team Template and follow the 3-step wizard:

1. Provider — choose Git or R2 and enter its details; pick your role.
2. Credentials — enter your token (Git) or access/secret keys (R2). For Git you can also set the commit identity (name + email) used for sync commits.
3. Test connection — Gridmux verifies the connection before you finish.

Click Complete setup to finish.

Publishing updates

As a manager, use Publish team template update to push the current profile to the shared remote. You confirm in a dialog first; members receive the new version on their next sync.

Receiving updates

Members get updates:

• Automatically, on a timer (about every 5 minutes by default).
• On demand, via Sync now.

When the remote has changed in a way that would overwrite local changes, Gridmux shows a drift confirmation before pulling, so an update never silently discards your local edits.

Conflicts

If both the local bundle and the remote changed since the last sync, Gridmux flags a conflict and asks you to pick Keep local or Keep remote. Before overwriting, a snapshot of the remote bundle is saved locally so the team’s content isn’t lost.

Backups & restore

Gridmux keeps backups of your bundle before overwriting it. Use Restore from backup… to roll back to a saved version — a safety snapshot of your current state is taken first.

One mode at a time

A device is configured for either Team Template or Cloud Sync, never both at once. If Cloud Sync is active, the Team Template tab shows an inactive banner; Disconnect the other mode first to switch.

Notes & limitations

• session.json is made portable before syncing — live terminal process IDs are stripped on push, and each member’s locally active workspace is preserved on pull.
• The bundle is the same five files in both modes, including team-notes.json. Splitting “team” content from “personal” content is a known limitation deferred to future work.