TouchUp is installed as an extension of VS Code, or as a desktop or web application on Windows and Linux. This page lists the files of a release, what each one installs and how to remove it.

## Files of a release

Each release of TouchUp contains these files. `<version>` is the number of the release.

| File | System | Content |
| --- | --- | --- |
| `touchup-win32-x64.vsix` | Windows | The extension for VS Code |
| `touchup-linux-x64.vsix` | Linux | The extension for VS Code |
| `touchup-<version>-win-x64-setup.exe` | Windows | Installer of the desktop and web applications, for the current user |
| `touchup-<version>-win-x64.msi` | Windows | The same applications as an MSI package, for the current user or for all users |
| `touchup-<version>-linux-x64.AppImage` | Linux | The applications in one executable file |
| `touchup-<version>-win-x64.zip` | Windows | Portable package, nothing to install |
| `touchup-<version>-linux-x64.tar.gz` | Linux | Portable package, nothing to install |
| `touchup-<version>-<part>.cdx.json` | All | Four files, one for the extension, one for the TouchUp service, one for the desktop application and one for the web application: the list of the software components of each, see [Security and releases](#security-and-releases) |
| `SHA256SUMS.txt` | All | The checksum of every file of the release |

Each installer or package is complete: no other software is needed.

## VS Code extension

### Install

1. Download the VSIX file of your system.
2. In VS Code, open the Extensions view, click `...` at the top, then `Install from VSIX...`, and select the file. Or, in a terminal: `code --install-extension <file>.vsix`.
3. The TouchUp icon appears in the activity bar, on the left.

VS Code 1.105 or later is needed. The workspace must be trusted: TouchUp connects to the controllers declared in the folder, and can write to them.

### Install on a PC without internet

The PC of a robot cell often has no internet, and VS Code cannot download the extension there. Prepare the file on another PC:

1. On a PC with internet, download the VSIX file of the system of the cell PC, from the files of the release or from the Marketplace page of TouchUp (the tab `Version History` of a version).
2. Copy the file to the cell PC with a USB key or a share.
3. On the cell PC, run `code --install-extension <file>.vsix` in a terminal, or use `Install from VSIX...` as above.

VS Code 1.105 or later must already be installed on the cell PC. TouchUp then works with no internet. A license also works offline, see [Offline and privacy](/touchup/documentation/license#offline-and-privacy). To install a newer version, copy its VSIX and install it the same way. Your configuration files and your backups are kept.

### Remove

In the Extensions view, right click TouchUp, then `Uninstall`. Your configuration files and your backups are kept.

## Desktop and web applications

### Windows

- **Setup**: run `touchup-<version>-win-x64-setup.exe`. TouchUp is installed for the current user in `%LOCALAPPDATA%\TouchUp`, without administrator rights, with a shortcut in the Start menu and on the desktop.
- **MSI**: run `touchup-<version>-win-x64.msi` and choose "just for you" or "for all users" (administrator rights). Silent install: `msiexec /i touchup-<version>-win-x64.msi /qn`, add `ALLUSERS=1` for all users.
- **Portable**: extract the zip file and run `touchup.exe`. Windows can block the files downloaded from the internet: run `Unblock-TouchUp.ps1`, at the root of the folder, once.

Install TouchUp with the setup or with the MSI, not both: they share the same folder and the same shortcuts.

### Linux

- **AppImage**: make the file executable (`chmod +x`), then run it.
- **Portable**: extract the `tar.gz` file and run `touchup`.

### Web application

Run `touchup-web` (`touchup-web.cmd` on Windows) in the folder of the application. It starts the server and opens the browser at `http://localhost:<port>/` (port 3000 by default, `--port <n>` changes it). Use `localhost`: the panels of TouchUp (the guide `Add a controller`, Status, the confirmation of a write) do not load at another address, such as `127.0.0.1`. The server answers the PC that runs it only. In the web application, the files and the backups are on the PC that runs the server, not on the PC of the browser.

### Open the web application to other PCs

To let the PCs of your network use one web application, start it in network mode, over HTTPS, at a host name:

```text
touchup --web --network --host touchup.plant.example --cert touchup.pem --key touchup.key
```

![In network mode, the browsers reach two names that point to the PC that runs TouchUp, over HTTPS.](/touchup/documentation/diagrams/web-network.svg)

What the PC and the network need:

- **A host name.** `--host` is a DNS name with a dot, for example `touchup.plant.example`. It cannot be an IP address, a name without a dot, or a name that has the label `webview`. Use a name for TouchUp only, not a name that other applications share.
- **The panels.** TouchUp shows its panels (the guide, Status, the confirmation of a write) at the name `*.webview.<name>`, for example `*.webview.touchup.plant.example`. Both `<name>` and `*.webview.<name>` must point to the PC that runs TouchUp, in the DNS of your network or in the `hosts` file of each client.
- **A certificate.** `--cert` and `--key` are the files (`.pem`) of a certificate whose alternative names are `<name>` and `*.webview.<name>` (a wildcard of one whole label), and that the browsers of the clients trust. TouchUp checks it at the start.
- **A current browser:** Chrome or Edge 76, Firefox 90, Safari 16.4 or later. An older browser cannot sign in.

If a condition is not met, TouchUp stops at once and says which one: it never starts half working.

At the start, TouchUp prints the access address with a random access token, for example `https://touchup.plant.example:3000/?token=...`. Open this address in the browser. A new token is made at each start. Give it only to the people who may use the application: whoever has it can use the controllers that the application reaches, so treat it as a password. The address stays in the history of the browser. The browser is not opened for you in this mode.

Keep the PC that runs TouchUp safe:

- Block the outgoing SMB (ports 139 and 445) and WebDAV connections of the PC, at its firewall. A link to a shared folder of another computer, opened from an email or a document, must not make the PC connect to it.
- Allow the port of TouchUp (3000 or the one of `--port`) from the PCs that need it only.

The network mode does not support IPv6 yet.

### Folders of other computers

The desktop application and the web application open only folders of the computer that runs them. A folder on a share of another computer (`\\server\share`) is refused, whether it comes from the list of the recent folders, a `.code-workspace` file, the command line or the dialog `Open Folder`. TouchUp shows `TouchUp opens only folders of the computer that runs it: the workspace on <host> was not opened. Copy the folder to that computer and open the copy.` A folder of a `.code-workspace` file that is on another computer is left out of the workspace.

A link to TouchUp cannot choose the folder to open either: the part of the address after `#` is ignored. The folder comes from the command line, from the list of the recent folders, or from your choice in a dialog. A link in an email or a web page cannot make the PC connect to a computer of someone else.

Some cases stay possible, so keep the firewall rule above:

- Browsing or typing `\\server\share` in the dialog `Open Folder` makes the PC read that share to show it, because you asked for it. In network mode, this is possible for whoever has the access token.
- A drive letter mapped to a share (`Z:`), or a link inside a folder that points to a share, is a folder of the computer for TouchUp. Do not open a folder that you do not trust.

### First start

On the first start, the desktop and web applications open with the guide `Add a controller` as the welcome page, see [Connect to your first controller](/touchup/documentation/first-connection), and with the Problems panel in the bottom panel, so that the problems that TouchUp finds in a program are in sight. Your own layout is kept at the next starts: if you close the panel or move it, it stays as you left it.

### Settings of the application

The desktop application keeps its own settings (the settings of the application, the keyboard shortcuts, the recent workspaces and the storage of the extensions) in `~/.touchup/desktop` (on Windows `%USERPROFILE%\.touchup\desktop`). The web application keeps them in `~/.touchup/web`. They are next to your global `~/.touchup/config.json`, which does not change.

At the first start, when the new folder does not exist and the settings folder of an earlier version does, TouchUp copies its content once: the settings, the shortcuts and the recent workspaces, not the extensions and the logs. The old folder is never changed or deleted. The cache files of the operating system stay in the folder of the operating system.

### Updates and removal

An installed application is replaced by the installer of a newer version. To remove it, use `Apps and features` on Windows, or delete the AppImage or the folder on Linux. Your settings and your backups are kept.

## Security and releases

What a release gives you to check what you install:

- **Signed Windows files.** The Windows programs of an official release (the executables of the extension, the setup, the MSI and the portable package) carry a digital signature. Windows shows the publisher, and a security tool can check it. A preview release can be unsigned: Windows or Smart App Control can then block it.
- **A list of components (SBOM).** Each release has four files `touchup-<version>-<part>.cdx.json`, one for the extension, the TouchUp service, the desktop application and the web application. They are in the CycloneDX format, a standard that security tools read. Each lists the software components that the part contains, with their versions and licenses, so that your IT team can check them against a list of known vulnerabilities. They list the components that are shipped, not the tools used to build TouchUp.
- **Checksums.** `SHA256SUMS.txt` gives the SHA-256 checksum of every file of the release, the SBOM files included. To check a download, compute the checksum of the file and compare it. On Windows: `Get-FileHash <file> -Algorithm SHA256`. On Linux: `sha256sum -c SHA256SUMS.txt`.

All these files are in the files of the release, next to the installers.

## What to read next

- [Connect to your first controller](/touchup/documentation/first-connection)