Projects
The project model in Lightpath — folder anatomy, switching projects, users, custom roles, and how syncing keeps every machine on the same page.
A project is the unit of configuration in Lightpath. Everything an install needs to operate — looks, scenes, playlists, outputs, devices, schedules, actions, logic rules, users, branding, media — lives inside one project folder. One Lightpath install can have many projects on disk and switch between them; one server runs one project at a time.
Folder anatomy
A project is a directory on disk. The pieces you'll interact with:
| File / folder | What's in it |
|---|---|
project.json | The project's configuration — every look, scene, playlist, palette, device, action, schedule, and output lives here. The source of truth. |
outputs/ | The TouchDesigner output components (.tox files), custom icons, 3D models, and any project-specific assets your outputs reference. |
plugins/ | Registered TouchDesigner plugins (sources, effects, system plugins) as .tox files. |
thumbnails/ | Cached preview PNGs of looks and scenes, used in the controller and content pickers. |
calendar.ics | The schedule, in iCalendar format. Drives the Schedule page. |
Most of a project is one config file plus a folder of TouchDesigner assets. Folders only appear if the corresponding feature is in use.
Where projects live on disk
- Windows:
%APPDATA%\Lightpath\projects\<project-name> - macOS:
~/Library/Application Support/Lightpath/projects/<project-name>
When an admin creates a project, they choose both a display name (what shows up in the UI) and a slug (the filesystem-safe identifier used for the folder name and URLs). The slug is set once at creation and doesn't change; the display name can be updated any time without disturbing links or references.
Switching projects
The project switcher in the top nav lists every project on this install that you have access to. Pick one and Lightpath loads its configuration, starts the right TouchDesigner outputs, and hot-swaps the UI to match.
A few things to know:
- Only one project runs at a time on a server. Switching is a real swap — the previous project stops, the new one starts.
- Offline user sessions are project-scoped — switching projects forces a logout for offline users. Cloud users stay logged in (their session is tied to your organization, not the project).
- Every connected client sees the switch happen live.
Users in a project
Lightpath has two parallel user systems and you'll likely use one, the other, or both:
Cloud users (default)
Users live in the cloud under your organization. They get access to every project in that organization via their org-level role. Authentication is email + password against the Lightpath cloud service. Cloud users keep working with up to 7 days of offline cache if the internet goes away, and they can be assigned to custom roles (see below).
Offline users
Project-scoped user records stored locally on the machine. Authenticate without any internet connection — designed for air-gapped installs.
Offline users must be enabled for the project by an admin before you can create them.
Offline users:
- Can only use the built-in system roles (no custom roles).
- Don't sync between machines — each install's offline users are independent.
When a user signs in, Lightpath tries the cloud first and falls back to offline users on LAN-only requests. See the HTTP API docs for the integration shape.
Roles and custom roles
Every user has a role. The role determines which pages they can see and what they can do.
System roles
Five built-in roles, in capability order:
| Role | What they can do |
|---|---|
| viewer | Read-only access to the active content. |
| kiosk | Activate content from the Kiosk; can't edit. |
| operator | Use the Controller; trigger actions; adjust schedules. |
| creator | Author content (looks, scenes, playlists). Can't manage users. |
| admin | Everything in this project. |
The hierarchy is the same on cloud and offline. System roles cannot be edited at runtime — the Roles UI shows them as read-only cards.
Custom roles
On cloud installs, custom roles can be created with bespoke permission sets — e.g. a Lighting Operator role that can change dimmers but not edit looks, or a Tour Tech role that can trigger content but can't modify it. Custom roles live with your organization and apply across every project in it.
Custom roles aren't available for offline users.
Syncing
Multi-machine installs and multi-user collaboration both depend on sync. Find it under Settings → Sync in the app.
The sync system keeps the project's configuration, calendar, output files, media, and thumbnails coherent across every machine on the install AND across every person editing the same project from different workstations.
Sync states
The sync section's status line tells you where you are:
| State | What it means |
|---|---|
| Synced | This machine matches the remote. No action needed. |
| Local changes to push | You've edited something the remote hasn't seen yet. |
| Remote changes available | Someone else (or another machine) pushed updates. |
| Out of sync — sync to merge | Both sides changed; sync will merge them. |
| Conflict | Both sides changed the same thing; resolve before syncing. |
| Not connected | This install has no sync remote yet. |
Hit the Sync button and Lightpath shows you a preview first — which files will upload, which will download, and any local deletions that exist remotely (so you don't lose work to a stale deletion). Confirm and it runs.
Version history
The History tab in the Sync section is a list of every sync that's happened on this project — each one with a date, an author, and a message describing what changed.
Three things you can do per entry:
- Label it — give it a memorable name (e.g. "Show open night v1", "Pre-rebrand baseline", "Before Saturday's update"). Labels stick with the entry and travel across machines so you can find a known-good state later by name.
- Restore to it — bring the project back to that version's state. Lightpath creates a new entry to record the restore, so the previous versions stay in the history — you can always go back further or jump forward again.
- Download files — pull a ZIP of the project at that exact point without restoring. Useful when you only need to recover one file (a media asset, a calendar from last season) without touching the live state.
Backups
The Backups tab is a list of automatic and manual snapshots — fuller copies of the project at known-good points (e.g., before a risky operation). Restoring from a backup brings that snapshot's state into the project as a new entry, the same way a version restore does.
Useful when you want to grab an older state explicitly, by name, without scrolling through the sync history.