Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/math-inc/OpenGauss/llms.txt

Use this file to discover all available pages before exploring further.

OpenGauss ships with a batteries-included shell installer that handles the Python environment, the local runner, and the shared opengauss installer flow in a single command. This page covers every supported installation path — hosted, macOS/Linux, Windows WSL2, and local vLLM — plus how to keep your installation up to date.
Prerequisites at a glance: git, ripgrep (rg), and either claude or codex installed and authenticated for the backend you plan to use. uv is auto-installed by the script if missing. tmux is strongly recommended so the installer can auto-attach you to the gauss session on completion.

​
Hosted path (fastest — 10 seconds)

If you do not want to install anything locally, open the pinned release environment on Morph: https://morph.new/opengauss-0-2-2 The session is fully pre-configured and ready in under 10 seconds. Claim or save the session early if Morph offers it, then use gauss-open-guide, gauss, /chat, or /project init to get started immediately.

​
macOS and Linux

The canonical local install path is a single ./scripts/install.sh invocation. This is the recommended approach for your own machine and usually completes in under 10 minutes.
1

Clone the repository

git clone https://github.com/math-inc/OpenGauss.git
cd OpenGauss
2

Run the installer

./scripts/install.sh
The script performs these steps in order:
  1. Installs uv if it is not already present
  2. Creates a repo-local installer environment
  3. Installs or upgrades the local runner
  4. Runs the shared opengauss installer flow on your machine
  5. Auto-attaches you to the local gauss tmux session, or prints the exact tmux attach -t gauss command if auto-attach is not possible
When the script finishes, you are either inside the gauss tmux session or one tmux attach command away from it.
3

Pass optional flags (if needed)

The installer accepts template-runner flags for headless or pre-keyed environments:
# Run without interactive prompts
./scripts/install.sh --plain

# Pre-seed your OpenAI API key
./scripts/install.sh --secret OPENAI_API_KEY=sk-...

# Pre-seed your Anthropic API key
./scripts/install.sh --secret ANTHROPIC_API_KEY=sk-ant-...
You can combine --secret flags. Keys are written to ~/.gauss/.env and loaded automatically on every gauss startup.

​
Windows (via WSL2)

OpenGauss on Windows runs through WSL2 using the same shared installer flow. All workflow agents run inside the Linux environment, which gives you the same terminal behavior and filesystem performance as a native Linux install.
Always clone and run OpenGauss from a Linux path such as ~/OpenGauss inside WSL. Do not use a Windows-mounted path like /mnt/c/Users/... — that will cause significant filesystem performance degradation and may break terminal behavior in tmux.

​
Updating an existing installation

To pull the latest changes and update your local runner, run these two commands from the cloned repository directory: 
cd OpenGauss
git pull
gauss update
gauss update re-runs the installer flow against the updated codebase and refreshes the local runner in place.

​
Local vLLM (running models on your own GPU)

If you want to avoid cloud API costs and have a local GPU available, you can point OpenGauss at a locally running vLLM server.
1

Start a vLLM server

Launch an OpenAI-compatible inference endpoint with your model of choice:
python -m vllm.entrypoints.openai.api_server --model <model_name>
By default vLLM listens on http://localhost:8000. Check your vLLM output for the exact address.
2

Point Gauss at the server

Either run the interactive setup wizard:
gauss setup
Or set the environment variable directly in ~/.gauss/.env:
OPENAI_BASE_URL=http://localhost:8000/v1
OPENAI_BASE_URL alone is enough — Gauss does not require an API key for local endpoints.

​
Verifying your installation

After installing, confirm everything is wired up correctly: 
gauss doctor
gauss doctor reports your managed-workflow backend, auth mode, uv and lake availability, and whether the current working directory resolves to an active Gauss project. It will tell you exactly what is missing before you attempt to launch a workflow.

Build docs developers (and LLMs) love

Get started for freeTalk to us