This guide describes a local install of DeepSearch on macOS.

1. Environment preparation

• Hardware: CPU 2+ cores (4+ recommended); RAM 4 GB+ (8 GB recommended).
• OS: macOS 14.0 (Sonoma)+
• Software: Git 2.40+, Python 3.11+ (❤️.14), uv 0.5.0+, MySQL 8.0+

2. Installation

1. Dependencies

1.1. Git

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" # if Homebrew missing

brew install git

git --version

1.2. Python and uv

brew install python@3.11

python3 --version

brew install uv
uv --version

1.3. MySQL (optional)

• SQLite: default DB_TYPE=sqlite.

• MySQL:

  brew install pkg-config
  brew install mysql
  

  brew services start mysql
  mysql -u root
  

  CREATE DATABASE openjiuwen_deepsearch;
  CREATE USER 'your_user_name'@'localhost' IDENTIFIED BY 'your_password';
  GRANT ALL PRIVILEGES ON openjiuwen_deepsearch.* TO 'your_user_name'@'localhost';
  FLUSH PRIVILEGES;
  

2. DeepSearch

2.1. Clone

• DeepSearch repo

  git config --global user.name your_username
  git config --global user.email your_useremail
  

  

  git config --global credential.helper store
  git clone https://gitcode.com/openJiuwen/deepsearch.git
  cd deepsearch
  

2.2. Start

cp .env.example .env
open .env

Encode special characters in passwords per the special character table.

 BACKEND_PORT=6000
 HOST=127.0.0.1

 DB_HOST=localhost
 DB_PORT=3306
 DB_USER=your_user_name
 DB_PASSWORD=your_password  

Use the same variable table as Linux local guide (BACKEND_PORT through OBS_*).

Checkpointer / OBS behavior: same as Windows local guide.

uv venv
uv sync --group backend

Hang / TLS: same notes as Linux guide.

uv run start_backend.py

If you see No module named 'greenlet', see the FAQ.

Expect Application startup complete.

3. FAQ

Special character URL encoding

Char	Encode	Char	Encode	Char	Encode	Char	Encode	Char	Encode
space	%20	"	%22	#	%23	%	%25	&	%26
(	%28	)	%29	+	%2B	,	%2C	/	%2F
:	%3A	;	%3B	<	%3C	=	%3D	>	%3E
?	%3F	@	%40	\	%5C	|	%7C	-	-

Why HTTP by default locally

Same as Windows local guide.