Install

Download and install the Tangle desktop app, the core service, the tangle CLI, device modules and the simulator on macOS, Windows or Linux.

Tangle ships as separate pieces so each machine gets only what it needs: an operator laptop runs the all-in-one desktop app, a rack server runs only the core service, a booth PC only needs the tangle command. This page lists the downloads, what each machine needs, and where Tangle keeps its files.

Note: Tangle is in early access. Public downloads and the one-line installer open with the public beta; until then we send the files directly. Request early access.

#What you can download

Each release publishes the files below at tangle.systems/download with a SHA256SUMS file to check them. <v> is the version and <target> the platform, for example aarch64-apple-darwin.

#Which pieces you need

#System requirements

Tangle runs on macOS, Windows and Linux. What else a machine needs depends on the device modules it runs:

When a module's runtime is missing or too old, the module does not start and the error names the program and the variable to set.

To check which modules a core can see:

tangle-core modules

#One-line install on Linux

On a Linux server (x64 or arm64, glibc 2.31 or newer: Debian 11, Ubuntu 20.04, RHEL 9 and later), one command installs the core service, the tangle command, the native device programs, the official device modules and a Node.js runtime:

curl -fsSL https://tangle.systems/install.sh | sh                          # for your user
curl -fsSL https://tangle.systems/install.sh | sudo sh -s -- --service     # for the machine, started at boot

The script downloads tangle-server-<v>-<target>.tar.gz from tangle.systems, checks it against the release's SHA256SUMS, unpacks it into /opt/tangle/<version> (~/.local/opt/tangle for a user) and puts tangle-core and tangle in /usr/local/bin (~/.local/bin). With --service, core listens on 0.0.0.0:7340 for other machines. Read it first at tangle.systems/install.sh.

Run the same command again to upgrade. The two newest versions are kept: to go back, run sudo ln -sfn <version> /opt/tangle/current and restart core.

The modules in the package are the catalog the designer installs drivers from; nothing is downloaded when you add a device.

#Desktop app

1. Download the installer for your platform and open it.
   • macOS: open the .dmg and drag Tangle to Applications. The disk image also holds tangle-sim; copy it to a folder if you want the simulator.
   • Windows: run the .msi or .exe.
   • Linux: install the .deb or .rpm, or run the .AppImage.
2. Open Tangle. It starts its own core on 127.0.0.1 on a free port, creates a token for itself and signs the designer in. You land on the project that was open last.

The app keeps its core's data in core/ in the app's data folder: the project library (core/projects/<project id>/project.json), modules, tokens and logs. Projects are opened, created, imported and exported from the designer's project menu.

The app's data folder:

The app's core stops when you quit the app. It does not conflict with a core service on the same machine: it uses its own port and data folder.

To work on another core instead (a server on the network), sign out and enter that core's address and a token. The sign-in screen offers Use the core on this computer to go back. See Designer.

Note: Until you activate a license in Settings > License, the app's core runs as the free designer: this computer only, and device connections and timelines pause every hour. To run a show for other machines, install the core service with a license.

#Core service

1. Extract tangle-core-<v>-<target>. Keep the ui folder next to the tangle-core program.
2. Start it:

./tangle-core run                          # the project open last, from the library, or a new one
./tangle-core run --project my-show.json   # or a project file of your own, edited in place

Without --project, core keeps its projects in a library in its data folder (tangle-core projects list), and the designer creates, opens and imports them. With --project, it runs that file. A project file needs at least an id and a name:

{ "id": "my-show", "name": "My show" }

3. To install drivers from the designer, put the module packages in a folder named modules next to tangle-core (one sub-folder per module), or point --catalog at another folder. Without it, install modules with tangle module add.
4. Open http://127.0.0.1:7340/designer. Create a token to sign in:

./tangle-core token create --name designer --scopes read,control,configure

#Accept other machines

By default core listens on 127.0.0.1:7340 and only this computer can connect. To let dashboards on tablets and other machines connect:

./tangle-core run --project my-show.json --listen 0.0.0.0:7340 --allow-remote --insecure-http

Warning: Traffic is not encrypted (no TLS yet). Use this on trusted show and control networks only.

#Install as a service

The service starts at boot, restarts after a crash and stops cleanly. Arguments after -- are passed to run.

macOS / Linux:

sudo ./tangle-core service install -- --project /shows/main.json --listen 0.0.0.0:7340 --allow-remote --insecure-http

Windows (administrator PowerShell):

.\tangle-core.exe service install -- --project C:\Shows\main.json --listen 0.0.0.0:7340 --allow-remote --insecure-http

It uses launchd on macOS, systemd on Linux and the Windows Service manager on Windows. Paths become absolute, and PATH and TANGLE_* variables are kept so node and python3 are found. On macOS and Linux, --user installs it for the current user, starting at login instead of boot.

To remove it:

sudo tangle-core service uninstall

A service runs as root on macOS and Linux and uses the machine-wide folders (see file locations). Manage its tokens and modules with sudo, for example sudo tangle-core token create ....

For redundant cores, see Redundancy.

#The tangle CLI

Extract tangle-cli-<v>-<target> and put tangle (tangle.exe on Windows) somewhere on your PATH, for example /usr/local/bin.

tangle module list
tangle discover

Run it with sudo (an administrator shell on Windows) to manage the modules of a core installed as a service. See CLI.

#Device modules

The desktop app includes the official modules. On a core service, install the modules your devices use, one package each:

tar -xzf tangle-module-misc.pjlink.projector-1.0.0.tar.gz
sudo tangle module add ./misc.pjlink.projector

Installing needs no internet and no npm install or pip install. tangle module add asks you to grant the permissions the module requests (network, serial, USB, MIDI, file system); --yes grants them without asking. Module ids look like <manufacturer or misc>.<product or protocol>.<category>, for example misc.pjlink.projector. See the device catalog.

#Simulator

The simulator runs virtual devices on this machine. Pick one form:

# Executable (Node.js built in)
./tangle-sim run examples/demo.json

# Script package (Node.js 20 or newer)
node tangle-sim.mjs run examples/demo.json

On macOS, if you copied tangle-sim from the .dmg, write the example configuration first:

./tangle-sim init
./tangle-sim run

The web UI opens at http://127.0.0.1:4380. See Simulator.

#File locations

Core and the CLI share these folders. TANGLE_HOME moves all of them into one folder.

Run as root (a service on macOS or Linux), core uses machine-wide folders instead:

Device passwords and keys are not stored in the project file. They go to the OS credential store (Keychain, Credential Manager, Secret Service). Where no store answers, such as a Linux service without a desktop session, they go to secrets.json in the data folder, readable by its owner only. TANGLE_SECRETS=file forces that.

#Environment variables

#Licensing

Without a license, core runs as the free designer (this computer only, pauses every hour) or, with --demo, in demo mode (10 devices, one-hour sessions). Activate a license on each machine that runs a show:

tangle-core license activate <key> --name stage-a
tangle-core license status

See Licensing for editions, offline activation and moving a license.

#Ports to open

Network discovery (tangle discover and the designer's scan) uses mDNS, SSDP (UDP 1900) and searches done by modules, so multicast must reach the core's network. On macOS, allow incoming connections when asked if other machines need to reach core or the simulator.