Operations

Run tangle-core in production: run options, services, file locations, logs, API tokens, remote access, backups, ports and upgrades.

This page covers running tangle-core on a show or building machine: how to start it, install it as a service, where it keeps its files, how to secure access, and how to back up and upgrade it.

#Run a project

tangle-core run --project /shows/main.yaml

Core loads the project, starts the device modules and serves every client surface on port 7340:

Before a show, check the project file without running it:

tangle-core check --project /shows/main.yaml

It exits with 0 when the project is valid and prints the number of rooms, devices, scenes and timelines.

#tangle-core run options

Other commands:

#Stopping

Ctrl-C, or SIGTERM on macOS and Linux (what launchd and systemd send), stops core cleanly: modules get a shutdown message, and core exits within about 5 seconds.

#Run as a service

A service starts at boot, restarts after a crash and stops cleanly. Core installs itself as a launchd daemon on macOS, a systemd unit on Linux, or a Windows Service. Put the run options after --.

macOS / Linux:

sudo tangle-core service install -- --project /shows/main.yaml --node-id core-a

Windows (administrator PowerShell):

tangle-core service install -- --project C:\Shows\main.yaml

To accept connections from other machines, add --listen 0.0.0.0:7340 --allow-remote --insecure-http to the options.

What service install does:

• Checks the options and loads the project first, so a mistake fails now and not at boot.
• Makes the project, module, log and UI paths absolute (services do not start in your current folder).
• Keeps the environment variables PATH, TANGLE_HOME, TANGLE_PYTHON, TANGLE_NODE and TANGLE_LOG, so node and python3 from Homebrew or a virtualenv are still found.
• With redundancy, takes the shared key from TANGLE_CLUSTER_KEY (or --cluster-key) and writes it to cluster.key in the data folder, readable only by the service, instead of putting it in the service definition.
• Installs and starts the service, named tangle-core.

With --user (macOS and Linux), the service runs for the current user and starts at login instead of boot.

To remove the service:

sudo tangle-core service uninstall          # macOS, Linux
sudo tangle-core service uninstall --user   # a --user service
tangle-core service uninstall               # Windows, administrator PowerShell

To restart it with your operating system's tools:

Note: A boot service on macOS and Linux runs as root and uses the machine-wide folders (see File locations). Manage its tokens and license with sudo, for example sudo tangle-core token create ..., so they land in the same folder.

#File locations

TANGLE_HOME moves everything into one folder: data in $TANGLE_HOME, logs in $TANGLE_HOME/logs. This is useful for portable installs.

Inside the data folder:

In a cluster, the primary copies device passwords to every backup over the encrypted cluster channel, so each backup's credential store holds them too. Device passwords and keys, and notification channel secrets, go to the OS credential store: macOS Keychain, Windows Credential Manager, or Secret Service on Linux. They never go in the project file. When no credential store is available (for example on a headless Linux server), core logs a warning and keeps them in secrets.json, readable only by its owner. Set TANGLE_SECRETS=file to always use the file.

#Logs

Core logs to the console (standard error) and to a daily log file in the log folder. Files are JSON lines named after tangle-core, and the last 14 days are kept.

Set the level with TANGLE_LOG:

TANGLE_LOG=debug tangle-core run --project show.yaml

The default is info. TANGLE_LOG accepts the usual filter syntax, for example TANGLE_LOG=info,tangle_cluster=debug for more detail from redundancy only. --log-json makes the console output JSON too.

#Audit log

audit.log in the log folder records every configuration change and control action as one JSON line: who did it, through which surface, what, on what, and the outcome.

{"at":1760362800000,"surface":"rest","caller":"stage-ipad","action":"timelines.control","target":"timeline show play","outcome":"ok"}

surface is rest, mcp, ws or cli. caller is the token name. outcome is ok or an error code such as missing_scope or not_primary.

#API tokens

REST, MCP, and WebSocket clients on other machines need an API token.

tangle-core token create --name stage-ipad --scopes read,control   # prints the secret once
tangle-core token list
tangle-core token revoke stage-ipad

The secret (starting with tgl_) is printed once and never stored: only its hash goes in tokens.json. Copy it when you create the token. Without --scopes, a token gets read,control.

Give each client its own token with the fewest scopes it needs, so you can revoke one without touching the others. A revoked token stops working at once, without a restart; WebSocket sessions using it are disconnected within 2 seconds.

Clients on the same machine can use the WebSocket without a token, with read and control.

Tokens belong to one machine. With redundancy, create each client's token on every node.

#Remote access

By default core listens on 127.0.0.1 and only the local machine can connect. To accept other machines:

tangle-core run --project show.yaml --listen 0.0.0.0:7340 --allow-remote --insecure-http

Core refuses to listen on a network address without --allow-remote, and, because there is no TLS yet, without --insecure-http.

Warning: Traffic, including API tokens, is not encrypted. Use remote access on trusted networks only: a dedicated show or control network, or a VPN. Do not expose port 7340 to the internet.

• REST and MCP calls from other machines need a token. WebSocket clients from other machines must send a token in their hello.
• In the free designer mode, remote access is always off: core serves this computer only, whatever the options.
• On Lite, the built-in designer and dashboards work remotely, but third-party REST and MCP calls are refused. See Licensing.

#Ports and firewall

Core also makes outbound connections:

• To devices, on the ports their modules use (see each module in the Device catalog).
• To the license server over HTTPS, to activate and refresh the license. Core runs without it; see Offline activation.
• For Sentinel: SMTP (587, 465 or 25), HTTPS to Twilio, ntfy, Pushover, Slack, Teams and your webhooks, and the hosts your probes check.

Open 7340 only to the networks your designer and dashboard clients use, 7341 only between cluster nodes, and 7342 only on the local network where you pair cores.

#Back up a project

Core writes every change back to the project file, in the same format (JSON or YAML) as it was loaded. The file is replaced in one step, so a crash never leaves it half written. Core writes the file from its own copy of the project, so formatting and YAML comments are not kept.

Back up:

• The project file.
• tangle.lock next to the project file, if you use one. It pins module versions; at start core activates the locked versions and warns about any that are missing.
• dashboards/<project id>/ in the data folder: drafts and published dashboard versions.
• Optionally sentinel/<project id>/ for the alert history.

Device passwords and channel secrets are not in the project file. Keep them in your own password manager so you can enter them again on a new machine.

Do not copy license/ or tokens.json to another machine: the license file only works on the machine it was issued for, and tokens are best created again per machine.

Note: If core cannot write the project file (disk full, permissions), it logs an error and the change stays live in memory. Check the log after changes made during a show.

To restore, put the project file back and start core with it. You can also export the project as JSON from the designer's Settings section, or read it with GET /api/v1/project.

#Upgrades

Release archives contain the tangle-core program and a ui folder. Keep ui next to the program.

1. Stop the show, or plan a moment when core can restart.
2. Replace tangle-core and the ui folder with the new version, in the same place. The service definition points to the program's path, so it picks up the new version.
3. Restart the service (see Run as a service), or start core again.
4. Check the log, the designer and tangle-core license status.

Device modules are installed and updated separately with the tangle CLI. Modules used by a running project are not removed or replaced under it. See CLI.

A perpetual license includes updates released until the updates until date shown by tangle-core license status.

With redundancy, keep every node on the same version. See Redundancy.