Install Ontology Studio

Choose your platform

Already installed? Jump to updates, preview releases, exact versions and rollback, offline installation, daily operation, or uninstall.

Before you start

• Install your container engine first and make sure it is usable from your terminal. The Studio installer checks the engine; it does not install it or start its virtual machine.
• Windows and macOS run the Linux image in an engine-managed Linux virtual machine. Windows Docker Desktop must use Linux containers. Linux can use Docker Engine or rootless Podman.
• The installer selects AMD64 or ARM64 from the engine's reported architecture. The chosen release must contain that architecture. There is no installer architecture override.
• Windows needs PowerShell. macOS and Linux need bash, jq, and standard Unix tools; online downloads also need curl. SHA-256 verification needs one of sha256sum, shasum, or openssl.
• A prebuilt Studio installation needs no Python, Node.js, Git checkout, container registry account, Compose, or Kubernetes setup.
• Use the same computer account and engine connection for installation and later operation. For Linux Podman, run Studio commands as your normal user without sudo.

The default browser address is http://localhost:5173/. If a development server or another application uses port 5173, stop that application or use the port options. Keep the same browser profile and exact address, including hostname and port, to retain access to your browser-stored work.

After installation

Wait for the installer to print Ontology Studio is ready with its version and address. It verifies the selected archive's size and SHA-256, checks the loaded image's version and architecture, and waits for the new application to respond successfully before reporting completion.

Open http://localhost:5173/, or the localhost address printed for your chosen port. Use Settings to enter optional AI provider details and your default business owner. You can import files and use local extraction without an AI key; AI analysis and imports from web links need network access.

The installer publishes the application only on host loopback (127.0.0.1). Studio is a local, single-user application without a multi-user login. The download website distributes the application; the running application and its data are on your computer.

Updates

Download the current installer again using your platform instructions, then rerun it. Choose stable explicitly to update to the current stable release, including when returning from preview:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP/ontology-studio-install.ps1" -BaseUrl 'https://ontology-studio.aidppowertools.com' -Channel stable

bash /tmp/ontology-studio-install.sh --base-url 'https://ontology-studio.aidppowertools.com' --channel stable

These management examples use the default settings directory. If you installed with a custom -InstallDir or --install-dir, supply it on every later installer run. The saved state restores the engine, port, container name, data volume, and release source when you do not override them. An initial install without an engine option defaults to Docker.

An update replaces the managed container while reusing the named volume. Browser data remains available at the same address and browser profile. Export important browser work and back up the server volume before changing releases; see your data.

If replacement startup fails, the installer attempts to restore the previous container and its former running or stopped state. It retains the volume. This is container recovery, not a snapshot or reversal of changes already made to data. On a failed first install there is no earlier container to restore.

Preview releases

Preview is available only when the release source contains a published preview channel. These commands switch the current installation to that channel:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP/ontology-studio-install.ps1" -BaseUrl 'https://ontology-studio.aidppowertools.com' -Channel preview

bash /tmp/ontology-studio-install.sh --base-url 'https://ontology-studio.aidppowertools.com' --channel preview

Use -Channel stable or --channel stable to return to stable. A run without a channel or version option follows the last installed channel, so a preview installation continues following preview. To keep your stable installation alongside preview, use a separate installation.

Exact versions and rollback

Use the exact version published in the release source, including its prerelease suffix when applicable. These commands ask for that version interactively, avoiding a hard-coded example that might not exist:

$releaseVersion = Read-Host 'Published version to install'
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP/ontology-studio-install.ps1" -BaseUrl 'https://ontology-studio.aidppowertools.com' -Version $releaseVersion

read -r -p 'Published version to install: ' release_version
bash /tmp/ontology-studio-install.sh --base-url 'https://ontology-studio.aidppowertools.com' --version "$release_version"

Run the shell example in bash. Exact versions use the form MAJOR.MINOR.PATCH with an optional prerelease suffix. Supply either a version or a channel, never both. The version directory and architecture archive must still be available on the release site or in your offline bundle.

To roll back, enter the retained earlier version. The installer uses the same verified replacement process and the same volume. Confirm that the earlier application can use your current data; restoring an application version does not restore a data backup.

An exact-version request selects that version for this run only. It does not permanently pin future runs: state records whether the installed release is stable or preview. Repeat the version option to keep selecting that exact release.

Offline installation

Obtain the complete release distribution from the publisher and copy it to the target computer. Keep its directory structure intact. The folder containing install.ps1, install.sh, and releases/ is the bundle root; a source-code ZIP alone is not an installation bundle.

bundle-root/
  install.ps1
  install.sh
  README.html
  releases/
    stable.json
    VERSION/
      release.json
      ontology-studio-VERSION-amd64.tar
      ontology-studio-VERSION-arm64.tar

VERSION represents an actual included version. Only the archive matching your engine's architecture is needed. A channel install also needs that channel's manifest (stable.json or preview.json) and the version it names. An exact-version install uses releases/VERSION/release.json directly.

Install the engine and prerequisites before disconnecting, and create/start its VM where required. Open a terminal in the bundle root. Choose your installed engine; these examples select Docker:

powershell -NoProfile -ExecutionPolicy Bypass -File ./install.ps1 -BundlePath . -Engine docker -Channel stable

bash ./install.sh --bundle . --engine docker --channel stable

For Podman, change -Engine docker to -Engine podman, or --engine docker to --engine podman. For a specific bundled version, replace the channel option with -Version or --version and the actual version. Do not combine a bundle path and a base URL.

The installer reads the image locally and verifies it against the bundled manifest. No image-registry download is needed. Optional AI analysis and web-link imports still need network access. The bundle location is remembered; retain it for future offline reinstalls, supply a new bundle path when it moves, or explicitly select -BaseUrl / --base-url to switch to online releases.

Your data

Browser records are not stored in the container volume. Changing from localhost to 127.0.0.1, using a different port, or switching browser profiles gives the browser a different storage location even when the server is the same. Return to the original address/profile to see that work again.

Linux container settings use an encryption key stored with the settings. Preserve ai-settings.key and ai-settings.json together when backing up the volume; whole-volume access can decrypt those settings. Do not replace a lost key expecting it to decrypt old settings. Native Windows development settings use Windows account protection and are not automatically migrated to the Linux container; enter provider keys again in Settings.

For a consistent server backup, stop Studio before copying the complete volume through your engine's volume-backup facilities, then start it again. Keep backups private. Copying the installer settings directory alone does not back up the server volume or browser records.

Release images and source packages exclude personal documents, browser records, and local provider settings. Choosing Analyze with AI sends extracted document passages and selected ontology context to the configured provider; provider billing applies.

Separate installations

Choose a unique settings directory, container name, data volume, and host port. This example creates an independent Podman preview installation on port 5174:

powershell -NoProfile -ExecutionPolicy Bypass -File "$env:TEMP/ontology-studio-install.ps1" -BaseUrl 'https://ontology-studio.aidppowertools.com' -Engine podman -Channel preview -InstallDir "$HOME/ontology-studio-preview" -ContainerName ontology-studio-preview -DataVolume ontology-studio-preview-data -Port 5174

bash /tmp/ontology-studio-install.sh --base-url 'https://ontology-studio.aidppowertools.com' --engine podman --channel preview \
  --install-dir "$HOME/ontology-studio-preview" --container-name ontology-studio-preview \
  --data-volume ontology-studio-preview-data --port 5174

Use docker instead if that is your chosen engine. Open http://localhost:5174/. This separate browser address starts with separate browser storage; import exported work when needed. Pass the same custom settings directory for future updates and use the custom container name in operational commands.

The installer refuses to switch engines inside an existing settings directory because Docker and Podman do not share volumes. To move engines, back up your data, create a separate installation, and migrate the needed data deliberately. The default port remains loopback-only.

Daily operation

Use the engine and container name chosen at installation. These commands work in PowerShell or a Unix terminal and operate on the default container:

Restart and stop allow up to 150 seconds for active requests to finish. Docker restart reference, Podman restart reference.

After reboot, start Docker Desktop or the Podman machine first where applicable, then start the container if necessary. The installer sets unless-stopped as the container restart policy, but it does not configure the engine or VM to launch at login. Linux rootless Podman boot behavior also depends on user-service configuration; see Podman's restart-policy documentation.

Use the installer to change its port or other launch options; a simple restart does not change those options. Both Studio installers run containers directly, so the commands above do not require Compose.

Uninstall

Default removal keeps your data. Stop and remove only the Studio container using the matching engine:

# Docker installation
docker stop -t 150 ontology-studio
docker rm ontology-studio

# Podman installation
podman stop -t 150 ontology-studio
podman rm ontology-studio

These commands also work in PowerShell. Substitute your custom name if you used one. The named data volume, browser records, loaded image, and installer settings directory remain. Reinstalling with the same engine, volume, browser profile, and address lets you reuse the retained data.

If you deliberately want to erase server settings and keys, first export or back up anything you need and remove the container. Then remove only its volume using docker volume rm ontology-studio-data or podman volume rm ontology-studio-data. This permanently deletes that volume's contents. Browser records are independent; clear the site's storage through your browser only if you also intend to erase them. You can remove the installer settings directory after recording any custom names or paths you need.

Installer options

All value-taking options require a separate value. Options below are supported by the current installers; there are no installer flags for automatic engine installation, architecture selection, uninstall, or opening the service to the network.

PowerShell also accepts the corresponding long options (--bundle, --base-url, and the other bash-style names). Container and volume names must start with a letter or digit, contain only letters, digits, underscores, periods, or hyphens, and be at most 128 characters. Explicit options override saved settings, except that an engine change requires a separate settings directory.

Troubleshooting

Engine unavailable

Run docker info or podman info in the same terminal and account used for installation. Start Docker Desktop or, on Windows/macOS, the existing Podman machine. If a command is missing, reopen the terminal after installing its CLI. On Linux, fix engine access or rootless prerequisites before retrying. On Windows Docker Desktop, confirm that Linux containers are selected.

Port conflicts

If installation reports an address already in use, inspect both engines if you have both installed. A native development server can also occupy port 5173. The commands below show listeners without stopping anything:

Get-NetTCPConnection -LocalPort 5173 -State Listen -ErrorAction SilentlyContinue | Select-Object LocalAddress, LocalPort, OwningProcess

# macOS
lsof -nP -iTCP:5173 -sTCP:LISTEN

# Linux
ss -ltnp 'sport = :5173'

Inspect container ports with docker ps and/or podman ps. Stop only the application you intend to replace, or rerun the Studio installer with -Port 5174 / --port 5174. A failed replacement attempts to restore the prior container. A port change creates a different browser storage origin; return to the old address or export/import work as needed.

Missing jq or checksum tools

On macOS/Linux, verify jq --version. Install it using the platform steps above. For archive verification, make one of sha256sum, shasum, or openssl available on PATH. The offline bundle does not install these prerequisites.

Missing release, checksum failure, or architecture mismatch

Check that the channel or exact version exists at your selected source and that its manifest includes the engine's architecture. A preview channel may not have been published yet. For an offline install, copy the complete manifest and referenced archive together. Redownload or recopy a mismatched file; do not edit its expected hash to make verification pass.

The manifest controls the expected archive hash and size. HTTPS and the release source establish trust in that manifest; the releases are not cryptographically signed. SHA-256 detects file mismatches but is not a publisher signature.

Container name already exists

The installer replaces only containers marked as managed by Ontology Studio. If an unmanaged container has the requested name, inspect it and choose a different Studio container name or rename the existing container deliberately. For independent installations, also use a unique settings directory, volume, and port.

Startup or update did not finish

Read the installer's error and inspect the container status and logs using daily operation. Startup is checked for up to 120 seconds. If the installer reports that rollback needs attention, inspect both the requested container and any container with a -rollback- suffix before changing them; the data volume is retained. Do not remove an install lock while another installer is active. After confirming an interrupted installer has stopped, remove only the exact lock directory named in its error, then retry.

Work or AI settings seem missing

Check the browser profile, hostname, and port first. For server settings, check that you selected the same engine, engine connection, computer account, and named volume. For restored encrypted settings, restore their matching encryption key too. See your data for the three separate storage locations.