How to Build and Run ArtCraft from Source

ArtCraft is open source under the MIT or Apache-2.0 license, so anyone can read, run, and modify the code. Running it from source is how Linux users get the desktop app today, and it is the first step if you want to contribute a fix or feature. This guide follows the official development setup in the storytold/artcraft repository.

What the app is made of

ArtCraft is a Rust and Tauri desktop app. Tauri pairs a Rust backend with a web frontend rendered in the operating system's own webview. In ArtCraft:

• the frontend is a React app built with Vite and Nx, under frontend/,
• the backend is a Rust workspace, communicating with the frontend through Tauri's native IPC,
• a local SQLite database stores desktop tasks, with migrations in _database/sql/artcraft_migrations/.

Backend services and website builds live in a separate artcraft-services repository, so this repo is all you need for the desktop app.

Prerequisites

You don't need a global Nx install; the launcher installs frontend dependencies locally.

Linux only: Tauri needs system libraries, most importantly WebKitGTK. Follow the Tauri prerequisites for Linux for your distribution before you start.

Run ArtCraft on macOS or Linux

1. Install the prerequisites

   Install Rust with rustup, Node.js 20+, and the Tauri CLI. On Linux, install the Tauri system dependencies as well.

2. Clone the repository

   git clone https://github.com/storytold/artcraft.git
   cd artcraft
   

3. Start the combined launcher

   ./script/artcraft/unix_dev.sh
   

   The launcher installs the frontend dependencies if needed, starts Vite, and then starts the Tauri app pointed at it.

4. Wait for the first build

   The first run compiles the whole Rust workspace, which can take a while. Later runs are much faster.

To start the port search somewhere other than 5193:

ARTCRAFT_DEV_PORT=6200 ./script/artcraft/unix_dev.sh

The launcher only uses free ports and never stops other processes. Press Ctrl-C to stop the frontend, the Rust watcher, and the desktop app together.

Run ArtCraft on Windows

Windows uses two PowerShell scripts, one for the frontend and one for the Rust app. Run each in its own terminal:

# Terminal 1: frontend dev server
.\script\artcraft\windows_frontend_dev.ps1

# Terminal 2: Tauri Rust application
.\script\artcraft\windows_rust_dev.ps1

How live reload works

The dev setup reloads automatically as you edit:

Useful commands for contributors

Check the Rust code without a database server:

SQLX_OFFLINE=true cargo check -p artcraft

Test the Unix launcher without compiling Rust or opening a window:

node --test frontend/scripts/unix-dev.test.mjs

Troubleshooting

• Rust compile errors on Linux usually mean a missing system library. Re-check the Tauri prerequisites for your distribution.
• The window opens but shows a blank page. Make sure the frontend server started; the launcher prints the port it chose.
• Login or media loading breaks after changing ports. The official repo includes desktop session regression checks for exactly this case; see docs/desktop-session-regression.md.
• Builds wait for a long time. Concurrent Rust builds share Cargo's build lock, so a second build waits for the first one to finish.

Contributing

Before you open a pull request, read the roadmap to see where the project is heading, and check open issues on GitHub. The team's stated goals include adding more models and providers, purpose-specific tools such as relighting and reposing, and reducing the app's dependence on hosted services.