Self-hosting
Docker (recommended)
docker run -p 3000:3000 -v ./data:/app/storage ghcr.io/tracefinity/tracefinity
The -v ./data:/app/storage mount persists your data between container restarts. Everything is served on port 3000 (frontend and API).
Environment variables
| Variable | Default | Description |
|---|---|---|
TRACERS | isnet | Comma-separated list of tracing models to load |
GOOGLE_API_KEY | Gemini API key for LLM-assisted tracing | |
GEMINI_IMAGE_MODEL | gemini-3.1-flash-image-preview | Gemini model for tracing (Docker default: gemini-3-pro-image-preview) |
REPLICATE_API_TOKEN | Replicate API token for remote tracing | |
REPLICATE_MODEL | men1scus/birefnet | Model to run on Replicate |
REPLICATE_RESOLUTION | Resolution for Replicate processing | |
FAL_KEY | fal.ai API key for remote tracing | |
FAL_MODEL | fal-ai/birefnet/v2 | Model to run on fal.ai |
FAL_OPERATING_RESOLUTION | 1024x1024 | Resolution for fal.ai processing |
STORAGE_PATH | ./storage | Data directory path |
Local tracers
Local tracers run saliency models in-process. They require ONNX Runtime and AVX CPU instructions. On non-AVX CPUs, local tracers are unavailable; use a remote tracer instead.
| Tracer | Quality | Speed | Min RAM |
|---|---|---|---|
isnet (default) | Good | ~0.8s/image | 2 GB |
inspyrenet | Good | ~2.8s/image | 6 GB |
birefnet-lite | Best | ~3.6s/image | 8 GB |
RAM figures are combined (tracer + U2-Net paper detection model) and tested in Linux containers.
Remote tracers
Remote tracers offload the saliency step to a hosted GPU. All OpenCV processing stays local. User photos transit the provider when a remote tracer is active.
| Provider | Env var | Notes |
|---|---|---|
| Replicate | REPLICATE_API_TOKEN | API predictions auto-purge after ~1h |
| fal.ai | FAL_KEY | Uses mask_only + sync_mode (result not stored in history) |
When no TRACERS env var and no LLM key is set, the provider is auto-detected from whichever token is present.
Tech stack
| Layer | Technology |
|---|---|
| Frontend | Next.js 16, React 19, TypeScript |
| 3D preview | react-three-fiber, Three.js |
| Backend | Python, FastAPI |
| 3D geometry | manifold3d, trimesh |
| Image processing | OpenCV |
| Local models | ONNX Runtime |
| Export formats | STL, 3MF |
Building from source
git clone https://github.com/tracefinity/tracefinity.git
cd tracefinity
# backend
cd backend
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
# frontend
cd ../frontend
pnpm install
# run both
cd ..
make dev
Backend runs on port 8000, frontend on port 4001.
Linting
make lint # run all linters
make lint-backend # ruff only
make lint-frontend # eslint + tsc --noEmit
make lint-fix # auto-fix where possible