Documentation

About Kiln

Overview

Kiln is the intelligence layer between idea and physical object. It provides a unified interface for AI agents to design, validate, and manufacture 3D-printed parts — controlling local printers, searching third-party model marketplaces (Thingiverse, MyMiniFactory, Cults3D), and routing jobs to fulfillment providers (Craftcloud) — all through the Model Context Protocol (MCP) or a 220-command CLI.

Clarification: Kiln does not operate its own marketplace or manufacturing network. It integrates with third-party marketplaces for model discovery and third-party fulfillment providers for outsourced manufacturing. Kiln is orchestration and agent infrastructure, not a supply-side platform.

Three ways to get to a print:

• 🖨️ Your printers. Control OctoPrint, Moonraker, Creality, Bambu Lab, Prusa Link, Elegoo, or Direct USB/Serial machines on your LAN — or remotely via Bambu Cloud when configured.
• 🌐 Third-party model search. Search external model repositories such as MyMiniFactory, Cults3D, and Thingiverse, then download where the provider permits, slice, and print.
• 🏭 Fulfillment providers. Route jobs to third-party fulfillment services like Craftcloud, or through connected provider APIs for overflow and specialty materials.

All three modes use the same MCP tools and CLI commands.

Non-goals:

• Operating a first-party marketplace or manufacturing network
• Replacing third-party supply-side platforms
• Owning marketplaces instead of integrating with them
• Acting as merchant of record for provider-routed manufacturing orders

Key properties:

• Local-first. Local printer communication stays on your network. No cloud relay, no accounts, no telemetry.
• Adapter-based. One interface covers OctoPrint, Moonraker, Creality, Bambu Lab, Prusa Link, Elegoo, and Direct USB/Serial. New backends plug in without changing upstream consumers.
• Safety-enforced. Pre-flight checks, G-code validation, and temperature limits are protocol-level — not optional.
• Agent-native. Every operation returns structured JSON. Every error includes machine-readable status codes. --json on every CLI command.

Supported Printers

Key Concepts

PrinterAdapter — Abstract base class defining the contract for all printer backends. Implements: status, files, upload, print, cancel, pause, resume, temperature, G-code, snapshot, stream URL, and optional bed mesh where the backend supports it.

PrinterStatus — Normalized enum: IDLE, PRINTING, PAUSED, ERROR, OFFLINE. Every backend maps its native state model to this enum.

MCP Tools — Typed functions exposed to agents via the Model Context Protocol. Each tool has a defined input schema and returns structured JSON.

MarketplaceAdapter — Abstract base class for searching third-party 3D model repositories. Implements: search, details, files, download. Concrete adapters for Thingiverse (deprecated — acquired by MyMiniFactory, Feb 2026), MyMiniFactory, and Cults3D (search only). Kiln does not host models — it searches external marketplaces.

MarketplaceRegistry — Manages connected marketplace adapters. Provides search_all() for parallel fan-out search across all third-party sources with round-robin result interleaving.

GenerationProvider — Abstract base class for text-to-3D model generation backends. Implements: generate, get_job_status, download_result. Concrete providers for Meshy (cloud AI), Tripo3D (cloud AI), Stability AI (synchronous cloud), Gemini Deep Think (AI-reasoned text/sketch-to-3D via Gemini + OpenSCAD), and OpenSCAD (local parametric). A GenerationRegistry auto-discovers providers from KILN_*_API_KEY environment variables.

Mesh Validation — Pipeline that checks generated STL/OBJ files for 3D-printing readiness: geometry parsing, manifold checks, dimension limits, polygon count validation. Uses pure Python (no external mesh libraries).

Job Queue — Priority queue backed by SQLite. Jobs are dispatched to idle printers by a background scheduler with history-based smart routing (best-performing printer for the job's file/material is preferred).

DeviceType — Enum classifying physical devices. Currently covers FDM printers with room for future device types.

DeviceAdapter — Alias for PrinterAdapter. Alternative import name.

Cross-Printer Learning — Agent-curated outcome database (print_outcomes table) that records success/failure/quality per printer and file. Safety-validated: rejects physically dangerous parameter values.

PaymentProvider — Abstract base class for payment processing backends. Implements: create_payment, get_payment_status, refund_payment, authorize_payment, capture_payment, cancel_payment. Concrete providers for Stripe and Circle (USDC).

PaymentManager — Orchestrates payment collection across providers. Routes to the correct rail (Stripe/Circle/crypto), enforces spend limits, persists transactions, and emits payment events.

HeaterWatchdog — Background daemon that monitors heater state and auto-cools idle heaters after a configurable timeout (default 30 min). Prevents heaters from being left on when no print is active.

PreviewGate — Single-use confirmation-token registry for print starts. A new non-resume start_print call must be preceded by a rendered preview that the user has approved; the token is bound to the file and printer and expires after a short TTL.

Pro Tool Manifest — Generated kiln-pro capability catalog bundled into public Kiln as pro_tool_manifest.json. It lets free-tier agents discover paid features, return structured tier-required messages, and proxy eligible calls through the hosted Kiln REST endpoint when a machine is paired, without moving proprietary kiln-pro source into the public repository.

LicenseManager — Provided by kiln-pro when installed. Public Kiln treats missing licensing as Free tier, while kiln-pro resolves Free, Pro, Business, and Enterprise entitlements and gates paid tools. Enterprise unlocks RBAC, SSO (OIDC/SAML), SCIM provisioning endpoints, audit trail export, lockable safety profiles, encrypted G-code at rest, per-printer overage billing, uptime SLA monitoring, and on-prem deployment. Local printer safety checks remain active regardless of license state.

How Kiln Works

A high-level map of Kiln's four core subsystems. These are what the "Before and After Kiln" comparison on the home page refers to. Deeper per-tool tables live further down this page; this section is for the reader who wants to understand the shape of the system before digging in.

1. The Validation Pipeline

Before a model ever reaches a printer, Kiln runs it through a printability analysis. The goal is simple: catch problems early so you don't waste filament, time, or bed adhesion on a print that was never going to work.

The pipeline scores a mesh across seven dimensions and returns a 0–100 score with a letter grade and a list of recommended fixes:

The last two dimensions are material-aware. Kiln knows ABS/ASA/PA/PC tend to warp, bed-slinger printers have less adhesion than CoreXY, and enclosures change everything. The output isn't a warning list — it's concrete slicer overrides: brim_width, raft_layers, reorientation suggestions, support placement.

Pure Python, no external mesh libraries. Runs locally on your laptop. Part of the patent-pending Printability Validation Pipeline.

2. The Decoration Engine

Kiln's decoration engine accepts many kinds of input and turns them into fabrication instructions for an FDM printer. The core idea: many inputs → one normalized heightmap → a printable decorated mesh.

Inputs the engine accepts:

• Photographs — your dog, a logo, a team photo. Auto-background removal, posterization to FDM-resolution depth tiers, heightmap conversion.
• Natural language — "add a wave texture to the side" or "emboss 'Happy Birthday' on top".
• Voice — the same, spoken aloud and transcribed.
• SVG — brand logos, icons, lettering.
• QR codes — generated to the right module size for the pocket's physical dimensions so a phone camera can actually scan the print.
• Procedural textures — tiger stripe, marble, snakeskin, wood grain, carbon fiber, honeycomb, lava, ocean, tie-dye, galaxy. Generated at face-centroid resolution; no UV mapping required.
• Brand assets — registered logos and imagery from a per-tenant brand asset registry for repeatable POS / merch / kiosk production.

Every input funnels through the same normalized-heightmap intermediate, then out to a CSG boolean on your mesh (emboss or deboss) that slices and prints on any Kiln-supported printer.

Covered by patent-pending Decoration Engine (KILN-017).

3. Git for 3D Printing

Version control for designs, decorations, and mechanical features — modeled after git, but operating on manufacturing-domain semantics instead of byte diffs.

Three artifact types, one substrate:

• Designs — the mesh itself.
• Decorations — logos, textures, photo-emboss, brand assets applied to a mesh.
• Features — chamfers, fillets, pockets, holes, bosses, ribs — the mechanical modifications.

All three get the same operations: branch, merge, pull request, release, cherry-pick, A/B analysis. You can:

• Branch in parallel — try three emboss depths without touching your proven version.
• Three-way semantic merge — merges operate on the manufacturing-domain fingerprint (Z-levels, pockets, bounding-box), not raw bytes. A conflict means two changes touched the same physical feature — which means something real.
• Sign a release with Ed25519 — after a version prints well, sign it. Anyone downstream can verify later that the mesh hasn't changed since you signed.
• Cross-branch A/B — correlate print outcomes with design changes across branches to see which variant actually printed best.
• Cherry-pick modifications — pull a single chamfer or a single decoration from one branch into another, conflict-aware.
• Local-first, optional sync — everything runs offline on your laptop. If you want to sync across devices or collaborate, push to your own Supabase-backed cloud — not a vendor's.

Covered by patent-pending Semantic Version Control for 3D Manufacturing (KILN-028) and Design Provenance + Manufacturing Intelligence (KILN-021).

4. The Cross-Printer Intelligence Layer

Every print outcome Kiln sees — success, failure, material, printer, settings, quality grade — goes into an outcome database. The intelligence layer reads from this database to make every subsequent print smarter:

• Proven recipes — the best-performing settings Kiln has ever seen for a given material-plus-printer combination. When you start a similar print, the agent gets these as a starting point instead of guessing.
• Regression alerts — if a design that used to print well suddenly stops, the system flags it with the version diff so you can see what changed.
• Cross-printer learning — a recovery strategy that worked on one Bambu A1 propagates as a candidate fix for a Prusa MK4 hitting the same symptom class. Fleet-wide learning, not per-machine.
• Predictive maintenance — failure-pattern analysis flags likely hardware issues (belt tension drift, hot-end clogging, bed-leveling regression) before they cause a scrapped print.
• Print confidence scoring — before a job starts, Kiln reports a confidence number based on historical outcomes for this material-printer-model combination.

Covered by patent-pending filings KILN-003 (autonomous failure detection + layer-accurate resume + cross-device learning), KILN-010 (closed-loop failure-to-prompt constraint synthesis), KILN-014 (cross-printer learning), and KILN-027 (cross-printer material learning).

How These Fit Together

A typical session strings all four together:

1. You describe or sketch what you want → a design is generated (text/image to 3D, OpenSCAD parametric, or search a third-party marketplace).
2. The mesh flows through the validation pipeline → score, grade, and any auto-fixes applied before slicing.
3. You branch, add a decoration or mechanical feature, maybe tweak depth or size, and start a print.
4. The intelligence layer suggests proven settings for your material and printer and flags any regression against past prints of this design family.
5. For multi-part work, the assembly JSON can also produce a PDF manual, page PNGs, BOM, verification gates, and a signed/embeddable 3MF manual manifest when kiln-pro is installed.
6. The print outcome is recorded against the version, so the next iteration is smarter than this one. If you like the result, sign the release — any downstream party can verify the exact mesh that shipped.

Every subsystem is optional. Free tier gets validation and basic design tools; decoration presets, mid-print modification, git-for-3D, assembly manuals, and cross-printer learning unlock with Pro. Business adds team approval gates, co-branded/multi-language manuals, QR product workflows, and per-part plate economics. Nothing about local printer control requires a cloud account — sync is opt-in.

Getting Started

Installation

# From PyPI
pip install kiln3d

# From source (development)
pip install -e ./kiln

Requirements: Python 3.10+, pip.

Discover Printers

kiln discover

Scans your local LAN (Ethernet or Wi-Fi) using mDNS and HTTP probing. If discovery does not find your printer, add it directly by IP with kiln auth.

Add a Printer

# OctoPrint
kiln auth --name ender3 --host http://octopi.local --type octoprint --api-key YOUR_KEY

# Moonraker
kiln auth --name voron --host http://voron.local:7125 --type moonraker

# Creality K1/K2/Hi-class local Moonraker
kiln doctor-creality --host 192.168.1.55 --model k1_max
kiln auth --name k1max --host 192.168.1.55 --type creality --printer-model k1_max

# Prusa Link
kiln auth --name prusa-mini --host http://192.168.1.44 --type prusaconnect --api-key YOUR_KEY

# Bambu Lab
kiln auth --name x1c --host 192.168.1.100 --type bambu --access-code 12345678 --serial 01P00A000000001

# Elegoo SDCP
kiln auth --name saturn --host 192.168.1.50 --type elegoo

# Direct USB / Serial
kiln auth --name ender3-usb --host /dev/tty.usbserial-0001 --type serial

Ethernet-Only Setup (No Wi-Fi)

Kiln works the same over Ethernet and Wi-Fi because it talks to printer APIs over LAN IP.

# Verify endpoint from your host:
curl http://192.168.1.44/api/v1/status                  # Prusa Link
curl http://192.168.1.50:7125/server/info               # Moonraker
curl http://192.168.1.55:7125/server/info               # Creality when local Moonraker is reachable
curl http://192.168.1.60/api/version                    # OctoPrint

# Register directly by IP (no discovery required):
kiln auth --name printer --host http://192.168.1.44 --type prusaconnect --api-key YOUR_KEY

First Print

kiln status                    # Verify printer is online
kiln preflight --material PLA  # Run safety checks
kiln upload benchy.gcode       # Upload file to printer
kiln print benchy.gcode        # Start printing
kiln wait                      # Block until complete

Slice and Print (STL to Object)

kiln slice benchy.stl --print-after

Auto-detects PrusaSlicer or OrcaSlicer, slices to G-code, uploads, and starts printing.

CLI Reference

Global Options

Commands

`kiln discover`

Scan the local LAN for printers via mDNS and HTTP probing. If no printers are found, use kiln auth --host <ip> to register directly.

`kiln auth`

Save printer credentials to ~/.kiln/config.yaml.

`kiln status`

Get printer state, temperatures, and active job progress.

`kiln files`

List G-code files available on the printer.

`kiln upload `

Upload a local G-code file to the printer.

`kiln print ... [--queue]`

Start printing. Accepts multiple files via glob expansion. With --queue, files are submitted to the job queue for sequential printing.

`kiln cancel`

Cancel the active print job.

`kiln pause` / `kiln resume`

Pause or resume the active print.

`kiln temp [--tool N] [--bed N]`

Get current temperatures, or set targets. Without flags, returns current temps.

`kiln gcode ...`

Send raw G-code commands to the printer. Commands are validated for safety before sending.

`kiln preflight [--material MAT]`

Run pre-print safety checks. Optional --material validates temperatures against expected ranges for: PLA, PETG, ABS, TPU, ASA, Nylon, PC.

`kiln slice [--print-after] [--profile PATH] [--output-dir DIR]`

Slice an STL/3MF/STEP/OBJ/AMF file to G-code. --print-after chains upload and print.

`kiln snapshot [--save PATH]`

Capture a webcam snapshot. --save writes to file; otherwise returns base64 in JSON mode.

`kiln wait [--timeout N] [--interval N]`

Block until the current print finishes. Returns exit code 0 on success, 1 on error/timeout.

`kiln history [--status S] [--limit N]`

Query past print records from the local database. Filter by completed, failed, cancelled.

`kiln printers`

List all saved printers with type and active status.

`kiln use `

Switch the active printer.

`kiln remove `

Remove a saved printer from config.

`kiln serve`

Start the MCP server (for agent integration).

`kiln cost [--material MAT] [--electricity-rate N] [--printer-wattage N]`

Estimate the cost of printing a G-code file. Analyzes extrusion, calculates filament weight and cost, and optionally includes electricity cost.

`kiln material set|show|spools|add-spool`

Material tracking commands. set records loaded material on a printer. show displays current material. spools lists spool inventory. add-spool registers a new spool.

`kiln level [--status] [--trigger] [--set-prints N] [--set-hours N] [--enable/--disable]`

Bed leveling management. Check status, manually trigger leveling, or configure auto-leveling policy.

`kiln stream [--port 8081] [--stop]`

Start or stop the MJPEG webcam streaming proxy. Proxies the upstream printer webcam stream to a local HTTP endpoint.

`kiln sync status|now|configure`

Cloud sync management. status shows sync state. now triggers immediate sync. configure sets cloud URL and API key.

`kiln plugins list|info`

Plugin management. list shows all discovered plugins. info shows details for a specific plugin.

`kiln install-mcp` / `kiln uninstall-mcp`

Install or remove Kiln from supported MCP clients. The installer detects common client config locations and writes the kiln serve entry for the current environment.

`kiln preview ` / `kiln validate ` / `kiln repair `

Render a model preview, check print readiness, or repair common STL/3MF mesh defects before slicing.

`kiln assembly-manual --assembly --out `

Generate a printable assembly manual when kiln-pro is installed. Public Kiln defines the assembly JSON contract; kiln-pro generates the PDF, per-page PNGs, BOM, and verification gates.

MCP Server Reference

Installation

The MCP server starts via kiln serve or python -m kiln serve.

Claude Desktop Integration

Add to ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "kiln": {
      "command": "python",
      "args": ["-m", "kiln", "serve"],
      "env": {
        "KILN_PRINTER_HOST": "http://octopi.local",
        "KILN_PRINTER_API_KEY": "your_key",
        "KILN_PRINTER_TYPE": "octoprint"
      }
    }
  }
}

Tool Catalog (Selected)

Kiln exposes 790 MCP tools and 797 total MCP capabilities. The most commonly used tools are documented below by category. Run kiln tools for the complete list.

kiln-pro tools are discoverable through the public pro_tool_manifest.json even when kiln-pro is not installed locally. Free-tier callers receive structured TIER_REQUIRED responses with the required tier and pricing URL; paired machines can proxy eligible paid-tier tool calls through the hosted Kiln REST endpoint so the paid code stays server-side.

Printer Control

File Management

Slicing

Monitoring

Fleet Management

Job Queue

Model Discovery

System

Cost Estimation (Quick Reference)

See Cost Estimation below for the full tool set including slice_and_estimate, compare_print_options, and material cost from mesh geometry.

Material Tracking

Material Intelligence

Bed Leveling

Webcam Streaming

Cloud Sync (Pro Tier)

Plugins

Billing & Payments (Business Tier)

External Provider Integrations *(As Integrations Launch)*

Kiln does not operate its own marketplace or manufacturing network. These tools integrate with third-party provider APIs for capacity discovery and job routing.

Safety Audit

G-code Interception

Emergency System

Fulfillment Services (Business Tier) — Third-Party Providers

Routes manufacturing to third-party fulfillment providers (Craftcloud). Kiln acts as an API client to these providers — it does not operate manufacturing capacity or act as merchant of record.

Consumer Workflow (No Printer Required)

Model Generation

Supported providers: meshy, gemini, tripo3d, stability, openscad. Set KILN_GEMINI_API_KEY, KILN_MESHY_API_KEY, KILN_TRIPO3D_API_KEY, or KILN_STABILITY_API_KEY to enable cloud providers. For original idea-to-part creation, prefer generate_original_design, which chooses idea-to-CAD backends and explicitly does not treat raw openscad compilation as natural-language generation.

Mesh Analysis & Repair

Pure-Python mesh operations — no external mesh libraries required. Operates directly on STL binary geometry for analysis, repair, transformation, and composition.

Parametric Design Templates

Design Advisor & Iteration

Original Design Audit & Design DNA

The generate_original_design / audit_original_design pipeline produces idea-to-part designs and validates them through a multi-gate readiness audit. Each audit gate (mesh validity, printability, design constraints, orientation, build volume) independently passes or blocks with severity levels.

When designs are generated via OpenSCAD (parametric), the pipeline preserves the parametric source code alongside the compiled mesh. This "Design DNA" allows agents to iterate on the design by modifying parameters rather than regenerating from scratch. The audit_original_design function chains: mesh validation, printability analysis (7-dimension), design intelligence constraint checking, auto-orientation scoring, and prompt improvement feedback — returning a single OriginalDesignAudit with a readiness score, blockers list, and next-action recommendations.

Print Analysis

Print Recovery & Failure Analysis

Firmware Updates

Vision Monitoring (Agent-Delegated)

Kiln provides structured monitoring data (webcam snapshots, temperatures, print progress, phase context, failure hints) to agents. The agent's own vision model (Claude, GPT-4V, Gemini, etc.) analyzes the snapshots for defects — Kiln does not embed its own vision model. Kiln adds lightweight heuristic validation (brightness/variance checks) to detect blocked cameras or corrupted frames.

Cross-Printer Learning (Pro Tier)

Printability Engine

7-dimension analysis of STL/OBJ meshes for FDM printing readiness. Pure Python (no external mesh libraries). Each dimension produces a typed dataclass result; the composite report includes a 0-100 score, letter grade (A-F), and actionable recommendations.

The last two dimensions (thermal stress and adhesion force) are material-aware heuristics. Thermal stress accounts for layer bonding weakness at sharp geometric transitions. Adhesion force estimation combines contact area, material shrinkage coefficients, and printer type (bed-slinger vs. CoreXY) to predict detachment risk.

Adhesion intelligence includes a decision matrix combining contact percentage, material warp tendency (_HIGH_WARP_MATERIALS: ABS, ASA, PA, PC, etc.), bed-slinger detection, enclosure status, and model height to produce concrete slicer overrides (brim_width, brim_type, raft_layers).

Adaptive Slicing

Warping Analysis (Pro Tier)

Multi-Part Assembly & Job Splitting

Splits large models or multi-part assemblies across multiple printers for parallel printing. Three split modes: build volume overflow (model exceeds one printer), multi-copy distribution (N copies across fleet), and assembly splitting (multi-STL archive across printers with reassembly instructions).

Assembly Manuals (Pro Tier)

Public Kiln owns the assembly JSON contract: parts, positions, materials, mating interfaces, clearances, optional fastener metadata, and magnet polarity when relevant. When kiln-pro is installed, the manual tools turn that contract into PDF instructions and page PNG previews. Multi-language and co-brand options require Business+.

Cost Estimation

G-code and 3MF cost analysis. Parses extrusion totals, calculates filament weight and cost from a 9-material database (PLA, PETG, ABS, TPU, ASA, Nylon, PC, PVA, HIPS), and optionally includes electricity cost from slicer-embedded time estimates. For 3MF files (including Bambu .gcode.3mf), extracts slicer metadata directly from the archive.

Part Economics (Business Tier)

Pipelines (Runtime)

Model Cache

Database Management

Printer Trust

Design Intelligence

Constraint-aware design reasoning — agents query material properties, design templates, and functional constraints before generating geometry.

Procedural Textures (Pro Tier)

Surface Decoration (Pro Tier)

QR Code & Product Generation (Pro Tier)

Enterprise Features (Enterprise Tier)

Procedural Textures (Pro Tier)

Mid-Print Modification & Resume (Pro Tier)

Design Provenance & Version Intelligence (Pro Tier)

Print Learning & Cross-Printer Intelligence (Pro Tier)

MCP Resources

Read-only resources for agent context:

Printer Adapters

OctoPrint

Communicates via HTTP REST. Requires an API key (generated in OctoPrint settings).

Configuration:

type: octoprint
host: http://octopi.local
api_key: YOUR_KEY

State Mapping: OctoPrint returns state as a set of boolean flags (printing, paused, error, ready, operational). The adapter maps flag combinations to PrinterStatus.

Webcam: Snapshots via GET /webcam/?action=snapshot.

Moonraker

Communicates via HTTP REST. No authentication required by default (Moonraker trusts local network).

Configuration:

type: moonraker
host: http://voron.local:7125

State Mapping: Moonraker returns Klipper state as a string (ready, printing, paused, error, shutdown). Direct mapping to PrinterStatus.

Webcam: Discovers cameras via GET /server/webcams/list, then fetches the snapshot URL.

Creality

Modern CrealityOS/Klipper FDM printers are supported through local Moonraker when it is reachable on the printer LAN. The creality backend probes common Creality Moonraker ports (7125, 80, 4408) and then delegates standard printer operations to the Moonraker adapter. Older Marlin-based Creality machines should use octoprint or serial.

Configuration:

type: creality
host: 192.168.1.55
printer_model: k1_max

Diagnostics: Run kiln doctor-creality --host 192.168.1.55 --model k1_max to verify /server/info, see the resolved Moonraker URL, and get same-LAN/IP/port/API-key guidance when local Moonraker is not reachable.

Caveat: Kiln should not claim every stock Creality firmware exposes local Moonraker. K1/K2/Hi/Ender V3 KE-class support depends on /server/info answering locally.

Bambu Lab

Communicates via MQTT over LAN. Requires access code and serial number (found in printer settings).

Configuration:

type: bambu
host: 192.168.1.100
access_code: "12345678"
serial: "01P00A000000001"

Note: Requires paho-mqtt package. Kiln gracefully handles its absence.

Prusa Link

Communicates via Prusa Link REST API (/api/v1/). Requires a Prusa Link API key.

Configuration:

type: prusaconnect
host: http://prusa-mk4.local
api_key: YOUR_KEY

State Mapping: Prusa Link returns state as a string (IDLE, PRINTING, PAUSED, FINISHED, ERROR, etc.). Direct mapping to PrinterStatus.

Limitations: No raw G-code or direct temperature control — these are managed through print files.

Elegoo (SDCP)

Communicates via the SDCP (Smart Device Control Protocol) over WebSocket on port 3030. No authentication required on local network. Covers Elegoo printers with cbd-tech/ChituBox mainboards: Centauri Carbon, Centauri Carbon 2, Saturn, Mars series.

Note: Elegoo Neptune 4 and OrangeStorm Giga run Klipper/Moonraker. Use the moonraker adapter type for those printers (port 4408 for Fluidd, 7125 for Moonraker API).

Configuration:

type: elegoo
host: 192.168.1.50
mainboard_id: ABCD1234ABCD1234  # optional, auto-discovered

Environment variables:

export KILN_PRINTER_HOST=192.168.1.50
export KILN_PRINTER_TYPE=elegoo
export KILN_PRINTER_MAINBOARD_ID=ABCD1234  # optional

State Mapping: SDCP returns numeric status codes. Mapping: 0=IDLE, 5/8/9/20=BUSY, 10=PAUSED, 13=PRINTING. Unknown codes default to UNKNOWN.

File Upload: SDCP uses a pull-based upload model — Kiln starts a temporary HTTP server, sends the printer a download URL, and the printer fetches the file. The printer must be able to reach the host machine on the ephemeral port.

Discovery: UDP broadcast of M99999 on port 3000. All SDCP printers on the network respond with their details.

Dependencies: Requires websocket-client package. Install with pip install 'kiln[elegoo]'.

Model Marketplaces (Third-Party Search)

Kiln provides a MarketplaceAdapter interface (mirroring the printer adapter pattern) for searching and downloading 3D models from third-party repositories. Kiln does not host or serve models itself — it searches external marketplaces on the user's behalf. A MarketplaceRegistry manages connected adapters and exposes search_all() for parallel fan-out across all sources.

Supported Marketplaces

Configuration

Set environment variables for each marketplace you want to enable:

export KILN_MMF_API_KEY=your_key               # MyMiniFactory developer key (recommended)
export KILN_CULTS3D_USERNAME=your_username      # Cults3D account username
export KILN_CULTS3D_API_KEY=your_key            # https://cults3d.com/en/api/keys
export KILN_THINGIVERSE_TOKEN=your_token        # Deprecated — Thingiverse acquired by MyMiniFactory (Feb 2026)

Adapters are auto-registered at server startup based on available credentials. Only configured marketplaces participate in searches.

Unified Search

search_all_models fans out the query to all connected marketplaces in parallel using a thread pool. Results are interleaved round-robin across sources for variety. If one marketplace fails (rate limit, timeout), results from the others still return.

Each result includes a source field identifying the marketplace, plus print-readiness hints:

• is_free — whether the model is free to download
• has_sliceable_files — has STL/3MF/OBJ files that need slicing
• has_printable_files — has ready-to-print G-code

Download and Upload

download_and_upload combines marketplace file download with printer upload in a single tool call. Accepts a source parameter to target any marketplace that supports downloads. Cults3D is excluded (metadata-only).

Safety Systems

Pre-flight Checks

Every print job should pass through preflight_check():

1. Printer online — Adapter can reach the printer
2. Printer idle — No active job running
3. File exists — Target file is on the printer
4. Temperature safe — Targets within safe bounds
5. Material validation — When --material specified, temperatures match expected ranges

Preview Confirmation

New non-resume print starts require a preview-confirmation token:

1. Render a model preview with visualize_model, preview_generated_model, or kiln preview.
2. Show the preview to the user and get approval.
3. Issue a preview token for the file/printer.
4. Pass that token to start_print.

Tokens are single-use, short-lived, and bound to the file plus printer. KILN_SKIP_PREVIEW_GATE=1 is the explicit advanced-user bypass and is logged whenever used.

G-code Validation

The validate_gcode() function screens commands before they reach hardware:

• Blocked: Firmware reset, EEPROM wipe, unsafe axis movements
• Warned: High temperatures, rapid moves without homing
• Passed: Standard print commands, temperature sets within limits

Temperature Limits

Authentication

Disabled by default. Enable for multi-user or network-exposed setups.

export KILN_AUTH_ENABLED=1
export KILN_AUTH_KEY=your_secret_key

Scopes: read, write, admin.

Read-only tools (printer_status, printer_files, fleet_status) never require authentication.

Webhooks

Register HTTP endpoints for real-time event notifications:

register_webhook(url="https://example.com/hook", events=["job.completed", "print.failed"])

Event types: job.submitted, job.dispatched, job.completed, job.failed, job.cancelled, print.started, print.paused, print.resumed, print.failed, printer.online, printer.offline, printer.error, stream.started, stream.stopped, sync.completed, sync.failed, leveling.triggered, leveling.completed, leveling.failed, leveling.needed, material.loaded, material.mismatch, material.spool_low, material.spool_empty, plugin.loaded, plugin.error, vision.check, vision.alert.

Payloads are signed with HMAC-SHA256 when a secret is provided.

Configuration

Config File

Location: ~/.kiln/config.yaml

active_printer: my-voron

printers:
  my-voron:
    type: moonraker
    host: http://voron.local:7125

  ender3:
    type: octoprint
    host: http://octopi.local
    api_key: ABC123

  x1c:
    type: bambu
    host: 192.168.1.100
    access_code: "12345678"
    serial: "01P00A000000001"

settings:
  timeout: 30
  retries: 3

Environment Variables

Precedence

CLI flags > Environment variables > Config file.

Development

Setup

git clone https://github.com/codeofaxel/Kiln.git
cd kiln
pip install -e "./kiln[dev]"
pip install -e "./octoprint-cli[dev]"

Running Tests

cd kiln && python3 -m pytest tests/ -v    # public Kiln test suite
cd ../octoprint-cli && python3 -m pytest tests/ -v  # 223 tests

Adding a New Printer Adapter

1. Create kiln/src/kiln/printers/yourbackend.py
2. Implement all abstract methods from PrinterAdapter in base.py
3. Return typed dataclasses — never raw dicts
4. Map all backend states to PrinterStatus enum
5. Handle connection failures gracefully (return OFFLINE)
6. Add to the adapter factory in cli/config.py
7. Write tests following the pattern in tests/test_server.py

Project Structure

kiln/src/kiln/
    server.py                 # FastMCP server, core tools, pro manifest stubs
    plugin_loader.py          # Auto-discovers public plugin modules
    preview_gate.py           # Preview-token gate for print starts
    slicer.py                 # PrusaSlicer/OrcaSlicer integration
    registry.py               # Fleet printer registry
    queue.py                  # Priority job queue
    scheduler.py              # Background dispatcher with smart routing
    events.py                 # Pub/sub event bus
    persistence.py            # SQLite storage
    webhooks.py               # HMAC-signed webhook delivery
    auth.py                   # API key authentication
    gcode.py                  # G-code safety validator
    safety_profiles.py        # Bundled safety database (44 named printer models)
    slicer_profiles.py        # Bundled slicer profiles
    printer_intelligence.py   # Printer knowledge base
    design_intelligence.py    # Material/pattern/constraint queries
    design_reasoning.py       # Design brief and reasoning helpers
    design_recipe.py          # Parametric design recipe persistence
    design_versions.py        # Public/local version metadata
    original_design.py        # Original design audit pipeline
    printability.py           # 7-dimension printability engine
    assembly.py               # Assembly JSON contract, joints, fasteners
    cost_estimator.py         # Whole-job cost estimation
    job_splitter.py           # Multi-copy, assembly, build-volume splitting
    model_visualizer.py       # Preview rendering and framing
    model_cache.py            # Local model cache
    backup.py                 # Database backup and restore
    skill_manifest.py         # Agent-facing capability manifest
    pro_tool_manifest.json    # Generated paid-tier discovery/proxy manifest
    plugins/                  # Auto-discovered public MCP tool plugins
        assembly_tools.py
        slicer_tools.py
        monitoring_tools.py
        printer_management_tools.py
        printability_tools.py
        recovery_tools.py
        estimate_tools.py
        smart_print_tools.py
        design_tools.py
        generation_tools.py
        fulfillment_tools.py
        marketplace_tools.py
        mesh_tools.py
        utility_tools.py
        ...
    printers/
        base.py               # PrinterAdapter + dataclasses
        octoprint.py
        moonraker.py
        bambu.py
        prusaconnect.py
        elegoo.py
        serial_adapter.py
    marketplaces/
        base.py
        myminifactory.py
        cults3d.py
        thingiverse.py
    generation/
        base.py
        registry.py
        gemini.py
        meshy.py
        tripo3d.py
        stability.py
        openscad.py
    cli/
        main.py
        config.py
        discovery.py
        install_mcp.py
        output.py

deploy/                  # On-prem Enterprise deployment
    k8s/                 # Kubernetes manifests (9 files: namespace, deployment, service, ingress, configmap, secrets, PVC, network policies, HPA)
    helm/kiln/           # Helm chart (12 files: Chart.yaml, values.yaml, templates/)

octoprint-cli/           # Auxiliary OctoPrint-only CLI package

docs/
    WHITEPAPER.md
    LITEPAPER.md
    PROJECT_DOCS.md
    THREAT_MODEL.md
    site/                # Astro docs site; whitepaper/litepaper/project docs render from these markdown files

The private kiln-pro companion repo extends the public surface through kiln_pro.bridge, kiln_pro.generate_manifest, and kiln_pro.rest_api. Its feature directories include paid-tier plugins, assembly manuals, design versioning, recovery intelligence, cloud sync, enterprise identity/compliance, billing/spend caps, fulfillment proxying, and the web workshop. Public Kiln should depend only on the bridge, generated manifest, and documented response contracts.

Kiln is a project of Hadron Labs Inc.