# How to Deploy LingBot-Map to Production: Interactive Streaming and Batch Rendering Guide

> Deploy LingBot-Map to production easily. Follow this guide for interactive streaming and batch rendering setup using PyTorch and pre-trained checkpoints. Get your project live now.

- Repository: [Robbyant/lingbot-map](https://github.com/Robbyant/lingbot-map)
- Tags: how-to-guide
- Published: 2026-07-19

---

**Deploy LingBot-Map to production by installing PyTorch 2.8.0 with CUDA 12.8, downloading the pre-trained checkpoint, and launching either the interactive Viser server ([`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py)) for real-time streaming or the batch renderer ([`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py)) for offline video generation.**

LingBot-Map is a feed-forward 3D foundation model maintained by Robbyant that reconstructs scenes from streaming image streams. Production deployment involves three layers: the **Model & Inference Engine** ([`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py)), **Pre-processing & Utilities** (`lingbot_map/utils/`), and **Serving & Rendering** ([`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) and [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py)). This guide provides the exact commands and configurations to deploy lingbot-map to production on a fresh server.


## Environment Setup and Dependencies

Production deployment requires an isolated Python environment with specific CUDA and PyTorch versions to ensure compatibility with NVIDIA Kaolin and FlashInfer.

### Install Python and PyTorch

Create a dedicated Conda environment using Python 3.10. The repository explicitly recommends **PyTorch 2.8.0 with CUDA 12.8** because NVIDIA Kaolin (required by the batch renderer) provides pre-built wheels for this combination.

```bash

# Create and activate isolated environment

conda create -n lingbot-map-prod python=3.10 -y
conda activate lingbot-map-prod

# Install PyTorch 2.8.0 with CUDA 12.8 support

pip install torch==2.8.0 torchvision==0.23.0 \
    --index-url https://download.pytorch.org/whl/cu128

# Install LingBot-Map in editable mode

pip install -e .

```

### Install FlashInfer and Optional Extras

FlashInfer provides the high-performance paged KV-cache attention implementation used by the Geometric Context Transformer (GCT) in [`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py).

```bash

# Install FlashInfer (recommended backend)

pip install --index-url https://pypi.org/simple flashinfer-python

# Optional: Install JIT cache for faster first-run compilation

pip install flashinfer-jit-cache -f https://flashinfer.ai/whl/cu128/flashinfer-jit-cache/

# Optional: Install visualization and rendering dependencies

pip install -e ".[vis,render]"

```

The `[vis,render]` extras include Open3D, PyYAML, and `onnxruntime-gpu`, which power the sky-masking utilities in [`lingbot_map/vis/sky_segmentation.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/vis/sky_segmentation.py) and the pose encoding helpers in [`lingbot_map/utils/rotation.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/utils/rotation.py).


## Download Pre-Trained Model Checkpoints

LingBot-Map offers three public checkpoints hosted on Hugging Face. For production stability with long sequences, download the "long" checkpoint (approximately 2 GB).

```bash

# Create checkpoint directory and download

mkdir -p /opt/lingbot-map/checkpoints
wget https://huggingface.co/robbyant/lingbot-map/resolve/main/lingbot-map-long.pt \
    -O /opt/lingbot-map/checkpoints/lingbot-map-long.pt

```

This checkpoint is optimized for the paged KV-cache attention mechanism and supports streaming inference beyond the base model's training range when combined with windowed processing modes.


## Production Deployment Modes

Choose between two production-ready entry points based on your use case: real-time interactive streaming or offline batch processing.

### Interactive Streaming Service (Viser UI)

Use [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) to launch a browser-based Viser viewer for real-time SLAM dashboards, remote robotics, or AR previews. This mode continuously updates a point-cloud visualization as new frames arrive.

**Key Production Flags:**

- `--mask_sky` – Enables automatic sky removal using the ONNX segmentation model in [`lingbot_map/vis/sky_segmentation.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/vis/sky_segmentation.py)
- `--keyframe_interval N` – Stores every N-th frame in KV-cache to reduce memory footprint for long streams
- `--use_flashinfer` – Forces the FlashInfer backend instead of native PyTorch SDPA
- `--offload_to_cpu` – Moves per-frame predictions to CPU RAM to stay within GPU memory limits (enabled by default)

**Production Command:**

```bash
python demo.py \
    --model_path /opt/lingbot-map/checkpoints/lingbot-map-long.pt \
    --image_folder /data/stream/images \
    --port 8080 \
    --mask_sky \
    --keyframe_interval 2 \
    --use_flashinfer \
    --offload_to_cpu

```

Access the interface at `http://localhost:8080` or configure the host IP for remote access. The server provides live camera trajectory visualization and point-cloud updates.

### Offline Batch Rendering (Headless MP4)

Use [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) for generating final videos, marketing content, or processing massive datasets without interactive monitoring. This mode compiles CUDA extensions (`voxel_morton_ext` and `frustum_cull_ext`) automatically on first run.

**Critical Flags for Long Sequences:**

- `--mode windowed` – Enables sliding-window inference required for sequences longer than the 320-frame RoPE training limit
- `--window_size 128` – Allocates 128 KV-cache slots per window (including 8 scale frames)
- `--overlap_keyframes 8` – Shares 8 keyframes between adjacent windows to maintain pose continuity
- `--sky_mask_dir` – Caches computed sky masks to avoid reprocessing

**Production Command:**

```bash
python demo_render/batch_demo.py \
    --video_path /data/batch/input_video.mp4 \
    --output_folder /data/batch/results \
    --model_path /opt/lingbot-map/checkpoints/lingbot-map-long.pt \
    --config demo_render/config/indoor.yaml \
    --mode windowed \
    --window_size 128 \
    --keyframe_interval 10 \
    --overlap_keyframes 8 \
    --mask_sky \
    --sky_mask_dir /data/batch/sky_masks \
    --sky_mask_visualization_dir /data/batch/sky_viz \
    --camera_vis default \
    --keyframes_only_points \
    --frame_tag \
    --frame_tag_position top_right \
    --save_predictions

```

The `--save_predictions` flag persists per-frame NPZ files for downstream analytics, while `--camera_vis default` overlays the trajectory on the output MP4.


## Production Readiness Checklist

Before handling live traffic, verify these production requirements:

1. **Hardware Verification** – Ensure GPU devices have at least 8 GB VRAM. FlashInfer works on any recent CUDA-compatible GPU, but larger batch sizes require proportional memory increases.

2. **Service Daemon Configuration** – Wrap your chosen entry point with a process manager to ensure automatic restart on failure. A minimal systemd service for the Viser UI looks like this:

```ini
[Unit]
Description=LingBot-Map interactive service
After=network.target

[Service]
Type=simple
User=lingbot
WorkingDirectory=/opt/lingbot-map
ExecStart=/opt/conda/envs/lingbot-map-prod/bin/python demo.py \
    --model_path /opt/lingbot-map/checkpoints/lingbot-map-long.pt \
    --image_folder /data/live_stream \
    --port 8080 \
    --mask_sky \
    --keyframe_interval 2 \
    --use_flashinfer
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

```

3. **Network Security** – Expose the Viser port (default 8080) behind an NGINX reverse proxy with SSL termination when serving external traffic.

4. **Persistent Storage** – Mount checkpoints at `/opt/lingbot-map` and configure `sky_mask_dir` on high-speed SSD storage to prevent I/O bottlenecks during batch processing.

5. **Monitoring Integration** – Import the logging utilities from [`benchmark/benchmark/utils/logging.py`](https://github.com/Robbyant/lingbot-map/blob/main/benchmark/benchmark/utils/logging.py) to capture structured logs, and monitor GPU memory using `nvidia-smi` to detect memory leaks during long streaming sessions.


## Containerized Deployment (Optional)

For containerized environments, use `nvidia/cuda:12.8.1-cudnn8-runtime-ubuntu22.04` as the base image. Execute the environment setup steps (1-5) inside the Dockerfile, then set the `CMD` to launch either [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) or [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) with your production flags. Ensure the container runtime provides GPU access (`--gpus all`) and mounts the checkpoint volumes.


## Summary

- **Environment**: Deploy using Python 3.10, PyTorch 2.8.0, and CUDA 12.8 to ensure compatibility with NVIDIA Kaolin and FlashInfer.
- **Model**: Download the "long" checkpoint (2 GB) from Hugging Face for optimal long-sequence performance.
- **Interactive Mode**: Use [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) with `--use_flashinfer` and `--keyframe_interval` for real-time Viser streaming on port 8080.
- **Batch Mode**: Use [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py) with `--mode windowed` and `--window_size 128` to process videos exceeding 320 frames.
- **Stability**: Implement systemd services, persistent checkpoint storage, and GPU monitoring for production reliability.


## Frequently Asked Questions

### What are the minimum GPU requirements to deploy LingBot-Map to production?

You need a CUDA-compatible GPU with at least 8 GB of VRAM. The FlashInfer backend operates efficiently within this constraint, though enabling `--offload_to_cpu` or increasing `--keyframe_interval` allows you to process longer sequences on memory-constrained hardware.

### Can I use a PyTorch version newer than 2.8.0?

You can use newer PyTorch versions for the interactive [`demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo.py) server, but the batch renderer ([`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py)) specifically requires PyTorch 2.8.0 because NVIDIA Kaolin ships pre-built wheels only for that version. Using a newer version forces Kaolin to compile from source, significantly increasing deployment time.

### How do I handle video sequences longer than 320 frames?

Use the windowed inference mode by passing `--mode windowed` to [`demo_render/batch_demo.py`](https://github.com/Robbyant/lingbot-map/blob/main/demo_render/batch_demo.py). Set `--window_size 128` (matching your GPU memory) and `--overlap_keyframes 8` to maintain pose continuity between windows. This configuration overrides the default RoPE positional encoding limits.

### Is FlashInfer mandatory for production deployment?

FlashInfer is not strictly required but highly recommended. Without it, the system automatically falls back to native PyTorch SDPA (Scaled Dot-Product Attention). However, FlashInfer's paged KV-cache implementation in [`lingbot_map/models/gct_base.py`](https://github.com/Robbyant/lingbot-map/blob/main/lingbot_map/models/gct_base.py) provides significantly higher throughput for streaming applications.