Skip to content

Back Up And Move Optima

Optima keeps everything it knows on the Gateway machine, in one folder: users, conversations, Assistants, Knowledge Bases, Connectors and their credentials, settings and certificates. This guide covers what to back up, how to restore it, and how to move Optima to a new machine.

By the end of this guide you will have a backup you can restore from, and — if you are moving — Optima running on the new machine with everything people had before.

Note

Optima has no backup button. A backup is a copy of its data folders, taken while its services are stopped.

What To Back Up

Most of what matters is in the Gateway's data folder. Each Node has a few settings of its own that are also worth keeping.

The Gateway's Data Folder

Platform Folder
Windows C:\ProgramData\Parker Software\OptimaGateway
Linux /var/lib/ParkerSoftware/OptimaGateway
macOS /Library/Application Support/Parker Software/OptimaGateway

Back up the whole folder. The parts that matter most are:

In the folder What it holds
config.json The Gateway's own settings, and the key every stored secret is encrypted with
optima.db Users, conversations, Assistants, Connectors and their credentials, settings, and access lists
Documents/knowledgebases/ Every Knowledge Base: its documents and their text
Documents/attachments/ Images people attached to conversations, encrypted
jwtsettings.json Sign-in sessions. Without it, everyone will have to sign in again
certificate.json, *.pfx The Gateway's certificate settings, and its certificate files
node-cert-pins.json The Node certificates this Gateway trusts
Branding/, ConnectorIcons/ The chat app's logo, and Connectors' icons
optima-analytics.db Analytics history. Optional — only the reports are lost without it
license.json, machine.id This machine's licence. See Moving to a new machine before restoring these anywhere else

Warning

config.json and optima.db belong together. The credentials in optima.db — Connector keys, sign-ins, the mail server's password — and the image attachments can only be read with the key in config.json. A backup of one without the other cannot be fully restored.

You can leave the following parts out to make the backup smaller. Optima will download or rebuild them by itself:

In the folder What it is
ScriptRuntime/, ConnectorDeps/, PipCache/, ConnectorRuns/ The Python runtime and Connectors' packages
Documents/knowledgebases/*/index/ Knowledge Base search indexes. Rebuilt from the documents, which takes a while for large ones and needs the embedding model running
Mcp/ Cached icons from the MCP directory
Logs/ Log files

Each Node

A Node's models can always be downloaded again, so a Node backup is about its settings:

What Where
The Node's settings, including its access key config.json in C:\ProgramData\Parker Software\OptimaNode, or /var/lib/ParkerSoftware/OptimaNode on Linux
Each model's settings — context window, instances, backend and the rest optima.executors.db in the Node's installation folder: C:\Program Files\OptimaNode, or /opt/OptimaNode on Linux
Models Executors/Models/ in the Node's data folder. Large; only worth backing up if downloading them again would be slow

What Is Not On The Gateway

Conversations are kept on the Gateway, so they are in the backup. Each person's Optima Chat app keeps a few things on their own device — their Workspace folders, tool activity, and which tools they ticked — and these are not part of a server backup.

Taking A Backup

The databases must not be changing while they are copied. Stop the services first, and start them again afterwards. You can do this with Stop and Start in the installer's Manage page (see Managing Optima), or with the commands below, which suit a scheduled backup.

Windows — in PowerShell, as administrator:

Stop-Service OptimaGateway, OptimaNode
Compress-Archive -Path "C:\ProgramData\Parker Software\OptimaGateway" `
    -DestinationPath "D:\Backups\optima-gateway-$(Get-Date -Format yyyy-MM-dd).zip"
Start-Service OptimaNode, OptimaGateway

Linux:

sudo systemctl stop OptimaGateway OptimaNode
sudo tar -czf /backups/optima-gateway-$(date +%F).tar.gz \
    -C /var/lib/ParkerSoftware OptimaGateway
sudo systemctl start OptimaNode OptimaGateway

Leave out OptimaNode if the Gateway machine runs no Node. People cannot use Optima while the services are stopped, so schedule backups out of hours.

Warning

Protect the backup as you would a password store. It holds every credential Optima has, together with the key that decrypts them. Keep it somewhere only administrators can reach, and encrypt it if it leaves the building.

Restoring On The Same Machine

You can go back to a backup on the machine it came from — for example, after a failed disk, or a mistake you need to undo:

  1. Install Optima, if it is not installed, at the same version as the backup or newer.
  2. Stop the services.
  3. Replace the Gateway's data folder with the one from the backup — all of it, license.json and machine.id included.
  4. Start the services.

Everything will come back as it was when the backup was taken. Anything created since — conversations, users, uploaded documents — will be lost.

Moving To A New Machine

A licence belongs to one machine, so a move releases it from the old one and activates it on the new one. Both machines need internet access for this. Without it, see Without internet access.

On The Old Machine

  1. Tell people Optima will be unavailable for the move.
  2. Open the Licence page and click Deactivate. This releases the serial number for the new machine. Optima will carry on running, with reduced limits.
  3. Stop the services, and take a backup as above.
  4. Note how the certificate was set up, in Settings → Security → Manage Certificates. If it came from the Windows certificate store, export it with its private key as a PFX file.

On The New Machine

  1. Install Optima, at the same version as the old machine or newer. See Installing Optima.
  2. Stop the services.
  3. Copy the backup into the Gateway's data folder, except license.json and machine.id. Leave those out: they belong to the old machine.
  4. Start the services, and sign in with your usual account.
  5. Open the Licence page and activate with your serial number. See Activating a licence.
  6. Set up the certificate again: upload the PFX file, or choose it from the new machine's certificate store. A certificate's password cannot be carried between Windows machines, so this is needed even when the files were copied. See Certificates and Security.
  7. Point your DNS record at the new machine.

Nodes

How you move a Node depends on where it runs:

  • A Node on the old Gateway machine moves with it: install the Node on the new machine too, and copy its config.json and optima.executors.db across before starting it. Its models can be copied or downloaded again.
  • A Node on another machine needs nothing, if the Gateway keeps the same address. If a Node itself moves, or is reinstalled, it has a new certificate, and the Gateway will refuse it until you click Trust new certificate on the Node. See Managing Nodes.
  • A Node installed afresh — moved, or reinstalled without its config.json — also has a new access key. Give it the Gateway's key on the installer's finish screen, or later from Manage. See Access Keys.

Check Everything Came Across

Once the new machine is running, check the following:

Check How
People can sign in Sign in to Optima Chat with an ordinary account
Conversations are there Open an old conversation, including one with an attached image
Connectors still work Ask an Assistant something that uses a Connector. If one reports a credential problem, the backup's config.json and optima.db did not come from the same copy
Knowledge Bases answer Search one on the Knowledge page. If its index was left out of the backup, rebuild it first
Nodes are connected The Nodes page shows each Node connected, with its models running
Email works Settings → Email → Send a test email

If the new machine has the same address and a certificate from your own certificate authority, people will notice nothing. If it uses the Gateway's self-signed certificate, the Optima Chat apps will show Certificate has changed the first time they connect, and each person will have to trust the new one. Tell people to expect it.