Skip to content

Getting Started

This page gives the fastest path from a fresh checkout to a running MatCreator session.

Installation

git clone https://github.com/AI4MS/MatCreator.git
cd MatCreator

pip install uv
uv venv .venv --python 3.12
source .venv/bin/activate

uv pip install -e .

Configure LLM Credentials

Use the MatCreator CLI to write persistent settings to ~/.matcreator/config.yaml:

matcreator config set llm.model=openai/qwen3-plus
matcreator config set llm.api_key=your-api-key
matcreator config set llm.base_url=https://api.example.com/v1

Check the current configuration without revealing secrets:

matcreator config show

See the Configuration page for the full config.yaml reference, including how to set up multiple LLM models with executor LLM cards.

Install the Vite frontend

The Vite frontend uses Ketcher and requires Node.js 24.14.1 or later. Install its dependencies with:

cd web/vite-frontend
npm install

Check the installed versions with: 

node --version
npx vite --version

Start the CLI

Automatic knowledge extraction and review keep their existing defaults of every 1 and 10 successful completed executions. During development, either process can be slowed down or disabled (0) as a persistent graph setting:

matcreator graph --memorize_frequency 0 --review_frequency 0
matcreator graph --memorize-frequency 5 --review-frequency 20

The command stores these values in ~/.matcreator/config.yaml. Explicit environment variables are also supported and take precedence in local mode:

export MATCREATOR_MEMORIZATION_FREQUENCY=0
export MATCREATOR_REVIEW_FREQUENCY=20

The web Settings → MatCreator tab exposes these knowledge frequencies, benchmark settings, and the tool-execution timeout. Python, Bash, and skill scripts time out after 3600 seconds by default; set a positive value there or persist the equivalent configuration:

runtime:
  execution_timeout_seconds: 3600

MATCREATOR_EXEC_TIMEOUT_SECONDS is the corresponding environment override.

Start an interactive session in the current project workspace:

matcreator chat --workspace .

By default, matcreator chat uses Flash mode for direct interaction. Use --plan for the full planning and graph-execution workflow:

matcreator chat --workspace . --plan

Try a simple prompt:

Generate a Li7La3Zr2O12 structure and save the result in the workspace.

MatCreator stores session data and generated files under the selected workspace.

Start the Web UI

bash script/start_matcreator.sh

This starts the ADK API server, FastAPI middle layer, and Vite frontend.

Open the frontend at:

http://localhost:5173

Useful Commands

Show saved configuration:

matcreator config show

Run a one-shot prompt without entering the chat loop:

matcreator run -p "Build a silicon FCC structure"

Query the knowledge graph:

matcreator knowledge query "structure generation"

Next Steps

  • Read the Overview to understand the harness architecture.
  • See the Configuration reference for the full config.yaml schema and multi-model LLM setup.
  • Choose a Deployment path for personal or shared use.
  • Learn how MatCreator's Knowledge layer works.