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

Install vite¶

For using vite frontend, you need to install it first:

cd web/vite-frontend
npm install
````
Make sure your system has node.js installed before installing vite.

Check vite installation with:
```bash
npx vite --version

Start the CLI¶

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.
Choose a Deployment path for personal or shared use.
Learn how MatCreator's Knowledge layer works.