Back to Liquid Agent DOCUMENTATION

Installation

Join the Waitlist

After your early-access application is approved, download and extract the package provided in your invitation, or clone it using the access details supplied to you. Keep this folder after the first installation; the launcher uses its code until the first successful update moves the application into managed versions. Python 3.11+ (3.12 recommended) and Node.js/npm must already be installed. The installer does not install Python or Node.

Packaged installers and open source

We plan to provide packaged installers that let you install LIQUID-Agent with a click. After the testing phase is complete, we will make the software open source. The open-source version will receive project updates sooner than packaged releases.

The guide below covers installation from source for the open-source version. During testing, use the source package or repository access provided to you.

One-command installation

Open a terminal in the extracted repository. If you use conda or a virtualenv, activate the environment you want before running the installer. All application Python dependencies are installed with that interpreter. Without an activated environment, the installer uses the Python on your PATH. It does not switch to a different application environment or bypass an OS-managed Python's protections.

macOS (Terminal or Finder):

./install_liquid_agent.command --user-data-dir "$HOME/Liquid Agent Data"

Linux:

bash install_liquid_agent_linux.sh --user-data-dir "$HOME/Liquid Agent Data"

Windows (PowerShell or Command Prompt):

.\install_liquid_agent_windows.cmd -UserDataDir "D:\Liquid Agent Data"

The Windows file applies a process-only PowerShell execution-policy override and delegates to the Windows installer. The Linux and macOS files only invoke the POSIX installer; Windows-specific command and PATH handling stays in the shared Python installer's Windows branches. The user data directory is required in both cloud and local modes. Choose a dedicated folder outside the repository. If you omit the path while running it in a terminal, the same installer asks you to enter one. The installer creates separate credentials/, memory/, skills/, tasks/, and models/ folders there. It remembers the selected path in each launch command. Upgrading the application does not replace this data. For an explicit interpreter, use LIQUID_AGENT_PYTHON=/absolute/path/to/python on macOS/Linux, or -Python C:\path\to\python.exe in PowerShell. Advanced conda users can set LIQUID_AGENT_ENV to an existing named environment.

The installer installs Python dependencies, builds the Web interface and bilingual docs, creates private user directories, and registers launch commands. Open a new terminal after installation. The commands remember the installation interpreter; conda installations automatically enter the captured environment by its prefix. A renamed/deleted environment requires reinstalling the launch commands.

liquid-agent       # Web workspace
liquid-agent cli   # Terminal interface
liq                # Short alias for Web
liquid-agent wiki  # Project homepage and documentation

liquid-agent web and liquid-agent client also open /#/agent. The public homepage's Try it opens this installation guide directly and does not check for or launch a local workspace. To enter an installed workspace, use the URL printed by the launcher. For a custom port, use liquid-agent wiki --port YOUR_PORT or the running service's URL.

Optional local model installation

Omit local to install for cloud LLM use. No model menu or weight download is started. To install a local model, use the same selected user data directory. Models are placed in its models/ child:

bash install_liquid_agent_linux.sh --user-data-dir "$HOME/Liquid Agent Data" local

.\install_liquid_agent_windows.cmd local -UserDataDir "D:\Liquid Agent Data"

On macOS, use ./install_liquid_agent.command --user-data-dir "$HOME/Liquid Agent Data" local.

A missing or relative user data path is an error before dependency installation. Quote paths containing spaces. This is private application storage, not the research-data disk selected later in the workspace.

The CLI menu lists reviewed multimodal Ollama candidates, download sizes and estimated working memory. Enter a number; OS, available RAM/VRAM and disk checks reserve room for scientific work. Native Ollama downloads the selected vision model and projector, applies the planned context and runs a basic tool/result probe. Assess multi-image, conversational and long-task performance on the machine where you will use the model.

For an 8 GiB GPU, the default 32K-context Qwen3.5 4B estimate may exceed the reserved VRAM budget. A shorter context can be requested explicitly with a JSON model list containing [{"model":"qwen3.5:4b","context_tokens":24576}], then install_liquid_agent_windows.cmd local -UserDataDir "D:\Liquid Agent Data" -ModelsList "C:\path\to\models.json" -Yes. This changes the capacity estimate and the installed model context; it is not a guarantee that the model will load or support the full scientific tool catalog on every 8 GiB device. Reduce other memory use and choose a larger context when the complete Web conversation does not fit.

Text-only Qwen3 GGUF choices have been removed. Eligible candidates include Qwen3.5 4B/9B, Qwen3.8 27B and Muse Glimmer 30B, based on their official model cards and subject to capacity checks. Existing profiles and keys are preserved. See Local Language Models. A successful installation probe does not establish scientific accuracy or long-task reliability.

Local installation preserves cloud keys and model pins. Switch between cloud and local profiles in the Web model menu or CLI whenever needed. Web-managed installs start their owned Ollama service when the user selects the installed model. For a CLI-only session, use liquid-agent local-models serve, then select its profile. When the last Web page closes, Liquid Agent asks this owned Ollama server to exit. An independently installed or user-started Ollama is never stopped by this action.

Advanced automation can use --user-data-dir PATH --with-local-models --model MODEL --yes (PowerShell: -UserDataDir PATH -WithLocalModels -Model MODEL -Yes). The legacy --models-dir flag remains supported only when it equals PATH/models. Installer --dry-run / -DryRun only skips model provisioning; it still installs dependencies and commands. For a model-only plan:

python -m liquidbiopsy_agent.local_setup setup --models-dir /absolute/path/models --dry-run

Update on macOS, Linux and Windows

The application checks for a newer stable GitHub Release when the local Web workspace opens. An available release appears in a dismissible notice. Closing it keeps the current version; Check for updates remains available in the workspace. The notice only offers the terminal command and release notes. It never installs automatically.

liquid-agent update --check
liquid-agent update
liquid-agent update --rollback

From the original repository folder, the equivalent scripts are ./update_liquid_agent.command on macOS and bash update_liquid_agent_linux.sh on Linux, or .\update_liquid_agent_windows.cmd on Windows. The updater uses the latest stable GitHub Release, prepares an isolated application version and Python environment, builds the Web interface and then switches the installed launcher. If preparation fails, the active version stays in place. The same selected user data directory, encrypted keys, memory, tasks, skills and local model files remain outside the application versions. Restart a running Web workspace after updating or rolling back. The first update also moves an existing editable installation to this managed layout. On Windows, managed versions are stored under %LOCALAPPDATA%\liquidbiopsy_agent\app; close the Web workspace before updating or uninstalling.

If an older installation does not recognize liquid-agent update, download the current release source and run its operating-system update script once. The script reads the existing installation receipt and uses its original Python environment to perform the first upgrade. Installations from before the required user data directory must first rerun the installer with --user-data-dir.

Safe uninstall

Close the Web workspace first; its owned Ollama server exits with it. If the model server was started without Web, stop it with Ctrl+C. Before the first update, run the uninstaller from the same checkout and Python environment used for installation. After an update, use liquid-agent uninstall so the active managed version handles removal. Preview the exact paths before removing anything:

bash scripts/uninstall_liquid_agent_cli.sh --dry-run --purge-private --purge-models
bash scripts/uninstall_liquid_agent_cli.sh --yes --purge-private --purge-models

For a managed installation, use:

liquid-agent uninstall --dry-run --purge-private --purge-models
liquid-agent uninstall --yes --purge-private --purge-models

Windows PowerShell:

.\scripts\uninstall_liquid_agent_cli.ps1 -DryRun -PurgePrivate -PurgeModels
.\scripts\uninstall_liquid_agent_cli.ps1 -Yes -PurgePrivate -PurgeModels

Without the purge flags, uninstall removes the active Python package, any previous editable package retained for rollback, managed application versions, registered launch commands and PATH entry. --purge-private also removes this installation's settings, saved credentials, conversations, memory and personal skills. --purge-models removes only a model directory created and marked as owned by this installer; an existing or unmarked model directory is preserved. The source checkout, input datasets and shared Python/Node dependencies are always preserved. If ownership cannot be verified, the uninstaller refuses the removal rather than guessing.

Browser site storage belongs to each browser profile and is outside the CLI's safe deletion scope. Before stopping Web, open ?reset-ui=1 on its local URL to clear that profile's cached conversation list immediately. A fresh installation also detects a different installation ID and clears the prior list on first open.

Private storage and task data

Installation requires a dedicated user data directory, separate from the source checkout. Choose input research-data folders independently within each task. Your selected parent contains credentials/, memory/, skills/, tasks/, and models/. Keep that parent when updating or reinstalling the application. For an existing installation, select its existing private application folder when upgrading, then move model files into its models/ child before local setup.

Private directories include configuration, credentials, memory, personal skills, and task state. Stored cloud and private-endpoint API keys use authenticated Fernet encryption; the master key is kept in macOS Keychain, Windows Credential Manager (local-machine persistence), or Linux Secret Service. There is no plaintext fallback. A locked or missing key store produces an actionable error. Headless systems may inject LIQUID_AGENT_VAULT_KEY from a secret manager; never commit or log this value. Environment-supplied provider keys need not be saved to disk.

These directories have no automatic cloud backup/upload mechanism in LIQUID-Agent. Private settings and global-memory directories cannot be attached as datasets. Global memory is excluded from cloud prompts by default. Personal guidance is disclosed only through the existing explicit skill-review boundary. Memory uses filesystem access controls; it is not encrypted by the application. They must also stay outside user-configured sync folders and source control. Cloud conversations still send the user's messages, permitted summaries and explicit image attachments to the selected provider; see Local Data and Privacy.

Optional scientific dependencies and diagnostics

The standard installer includes web,docs,ml,assay-tables,tools,skills. Specialized encoders and file formats may need separate dependencies or external programs. Do not install all incompatible ML runtime pins into one environment blindly.

python -m pip install -e ".[blood-io]"
python -m pip install -e ".[report]"

blood-models is a separately constrained scientific encoder extra. local is the local provisioning extra; local-llm is not an extra. Native scientific package availability varies by OS, especially pysam, pyBigWig and external Unix tools. WSL follows the Linux installation path rather than the native Windows path.