Empty spools don't belong in the trash! We support the Recycling Fabrik. Send your empty filament spools and 3D printing waste there to have it recycled into new filament.
Exciting News: Recycling Fabrik is the first manufacturer that will soon start shipping their filament spools with pre-programmed, FilaMan-compatible RFID tags!
Looking for the German version? Read the README.de.md.
FilaMan is a comprehensive filament management system for 3D printing. It helps you keep track of your filament spools, manufacturers, colors, and current stock levels. It also features integrations with printers and AMS (Automatic Material System) units.
The full user manual is available at docu.filaman.app.
To unlock the full potential of this system, we highly recommend our companion hardware project: FilaMan-System-ESP32 With this ESP32-based smart scale and RFID integration, you can simply place your spools on the scale, automatically measure the remaining weight, and sync the data seamlessly with this software via RFID tags!
If you are using Home Assistant, install FilaMan from our add-on repository: Fire-Devils/filaman-ha-app Add that URL under Settings → Add-ons → Add-on store → ⋮ → Repositories, then install FilaMan and run it directly inside your Home Assistant environment.
Connect FilaMan to Bambu Lab printers and AMS units with the Bambuddy driver plugin. The integration keeps spool and AMS information in sync, supports automatic assignment after weighing and inserting a spool, and reports filament usage back to FilaMan.
When used with Bambuddy, FilaMan can also apply your custom, Bambu Cloud-synced slicer profiles automatically when a spool is placed in an AMS slot. The correct material profile is then available in both the AMS and Bambu Studio, giving custom and third-party filament much the same seamless workflow as an official Bambu RFID spool.
- Spool Management: Track remaining weight, location, and status.
- Dual RFID Tags: Store two RFID tag UIDs per spool, so either side of a dual-tag spool can identify the same inventory item.
- Multi-User: Role-based access control and tenant support.
- Printer Integration: Plugin system to connect with 3D printers and AMS units.
- Bambuddy Integration: Synchronize spool inventory and AMS assignments, track filament use, and automatically apply custom Bambu Cloud slicer profiles.
- Printable Labels: Print and export spool or filament labels with QR codes, custom label designer layouts, and label-paper sheet output.
- Database Support: Works with SQLite (default), MySQL, and PostgreSQL.
- Responsive UI: Modern design with light, dark, and brand themes.
- OIDC (OAuth2) Login: Single Sign-On (SSO) via OpenID Connect for existing users.
We have exciting plans for the future of FilaMan:
- Printer Plugins: Develop plugins to connect with various 3D printers (community contributions are highly welcome!).
- Mobile Apps: Dedicated apps for iOS and Android.
The easiest way to start FilaMan is using Docker:
docker run -d \
--name filaman-system-app \
--restart unless-stopped \
--pull always \
-p 8083:8000 \
-v filaman_data:/app/data \
ghcr.io/fire-devils/filaman-system:latestThe application will be available at http://localhost:8083.
- Default Email:
admin@example.com - Default Password:
admin123
- Docker
- Docker Buildx with multi-architecture support (for ARM/AMD)
git clone https://github.com/Fire-Devils/filaman-system.git && cd filaman-system
# Build image
docker build -t filaman-system:latest .
# Or with docker-compose
docker-compose up --build
# Start container
docker run -d \
--name filaman-system-app \
--restart unless-stopped \
-p 8083:8000 \
-v filaman_data:/app/data \
-e DEBUG=false \
-e SECRET_KEY=your-secret-key \
-e CSRF_SECRET_KEY=your-csrf-secret \
-e ADMIN_EMAIL=admin@example.com \
-e ADMIN_PASSWORD=your-admin-password \
filaman-system:latest- Python 3.11+
- Node.js 18+
- uv (Python Package Manager)
cd backend
uv sync
uv run uvicorn app.main:app --reloadThe API will be available at http://localhost:8000.
cd frontend
npm install
npm run devThe frontend will be available at http://localhost:4321.
cd frontend
npm run buildThe static files will be in frontend/dist/.
Create a .env file in the project root directory. Use .env.example as a template:
# Database Configuration
# SQLite (default):
DATABASE_URL=sqlite+aiosqlite:///./filaman.db
# MySQL:
# DATABASE_URL=aiomysql://username:password@hostname:3306/database
# PostgreSQL:
# DATABASE_URL=asyncpg://username:password@hostname:5432/database# Generate single secret
openssl rand -hex 32
# Generate all secrets at once
echo "SECRET_KEY=$(openssl rand -hex 32)"
echo "CSRF_SECRET_KEY=$(openssl rand -hex 32)"
echo "OIDC_ENC_KEY=$(openssl rand -hex 32)"To enable OIDC (OpenID Connect) login, set the following environment variable:
# Required for encrypting the OIDC client secret in the database
OIDC_ENC_KEY=your-fernet-keyNote: When using MySQL or PostgreSQL, backups must be managed externally by the administrator. The automatic SQLite backup is disabled in this case.
/
├── backend/
│ ├── app/
│ │ ├── core/ # Config, database, security
│ │ ├── modules/ # Domain modules
│ │ └── plugins/ # Printer plugins
│ ├── alembic/ # Database migrations
│ └── tests/ # Backend tests
├── frontend/
│ ├── src/
│ │ ├── pages/ # Astro pages
│ │ ├── layouts/ # Page layouts
│ │ └── components/ # UI components
│ └── dist/ # Production build
└── spec/ # Project specifications
Backend:
- FastAPI
- SQLAlchemy 2.0 + Alembic
- Python 3.11+
Frontend:
- Astro + Tailwind CSS
- Static Build
MIT