Cleanroom Labs
About
Blog
Docs
dev
Development documentation — may change at any time
AirGap Deploy
Documentation
Overview
Features
How It Works
Quick Start
Prerequisites
Installation
First Deployment
Usage
Preparing Packages
Validating Manifests
Creating Manifests
Listing Components
Manifest Reference
Package Section
Targets Section
Components
Rust Application
External Binary
Model File
System Package
Installation Configuration
Examples
Example 1: Rust Application with Dependencies
Example 2: Large ML Application
Integration with AirGap Transfer
Platform Support
Building
Documentation
Start Here
Technical Documentation
Project Planning
Meta-Architecture
Use Cases
Privacy
Why AirGap Deploy?
License
Contributing
Roadmap
Use Cases
Use Case Analysis
Purpose
User Personas
Release Engineer
Application Developer
IT Administrator
Open-Source Maintainer
Primary Use Cases
Cleanroom Whisper Deployment
Ollama Deployment
Common Requirements Across All Use Cases
Integration Scenarios
With AirGap Transfer
With Cleanroom Whisper
With CI/CD Systems
Out of Scope
Success Metrics
See Also
Use Case: Cleanroom Whisper Deployment
Overview
Developer Workflow: Creating Release Packages
Prerequisites
Step 1: Prepare AirGapDeploy.toml
Step 2: Local Testing (Optional)
Step 3: Configure GitHub Actions for Multi-Platform Builds
Step 4: Create Release
Step 5: Verify Release
User Workflow: Installing on Air-Gapped System
Prerequisites
Step 1: Download Package
Step 2: Transfer to Air-Gapped System
Step 3: Extract Package
Step 4: Review Package Contents
Step 5: Run Installation Script
Step 6: Installation Process (Interactive Mode)
Step 7: First Run
Alternative: Non-Interactive Installation
Troubleshooting
Installation fails: “C compiler not found”
Installation fails: “ALSA not found” (Linux only)
“cleanroom-whisper: command not found”
Tray icon doesn’t appear (GNOME)
Package Size Estimates
Version Update Workflow
Developer Side
User Side
Summary
Use Case: Ollama Deployment to Air-Gapped System
Scenario
Prerequisites
Workflow Steps
Phase 1: Preparation (Connected Machine)
Phase 2: Physical Transfer
Phase 3: Installation (Air-Gapped Machine)
Success Criteria
Variations
Multiple Models Deployment
Update Existing Installation
Error Scenarios
Integration Points
With AirGap Transfer
With Configuration Management
Security Considerations
Post-Deployment Verification
Related Documents
Use Case: SBOM/CBOM Generation During Deployment Packaging
Scenario
Prerequisites
Workflow Steps
Phase 1: Preparation (Connected Machine)
Phase 2: Transfer
Phase 3: Usage on Air-Gapped Side
Success Criteria
Error Scenarios
Related Requirements
Related Documents
Use Case: Offline Vulnerability Scanning
Scenario
Prerequisites
Workflow Steps
Phase 1: Database Preparation (Connected Machine)
Phase 2: Transfer
Phase 3: Scanning (Air-Gapped Machine)
Phase 4: Remediation Planning
Success Criteria
Error Scenarios
The Update Cycle
Related Requirements
Related Documents
Gap Analysis: Cleanroom Whisper Deployment
Current Design Coverage
Critical Gaps Identified
Gap 1: Post-Installation Configuration
Gap 2: Multiple Model Support
Gap 3: Cross-Platform Packaging
Gap 4: Installation Locations & Permissions
Gap 5: Dependency Verification
Use Case Matrix
Use Case 1: Developer Creating Release (Primary)
Use Case 2: End User Installing on Air-Gapped System (Primary)
Use Case 3: Advanced User Custom Build (Secondary)
Use Case 4: Enterprise Deployment (Future)
Architectural Recommendations
Recommendation 1: Add Post-Install Configuration with Auto-Discovery
Recommendation 2: Optional Components
Recommendation 3: Installation Modes
Recommendation 4: Dependency Verification
Phase Priority Adjustments
Current MVP (v1.0)
Recommended MVP (v1.0)
Example: Complete Cleanroom Whisper Manifest
Cleanroom Whisper Runtime Behavior
Summary
Does Current Plan Support Cleanroom Whisper?
Recommended Actions
Software Requirements Specification
Introduction
Purpose
Scope
Definitions, Acronyms, and Abbreviations
Overall Description
Product Perspective
Product Functions
User Characteristics
Constraints
Assumptions and Dependencies
Functional Requirements
Manifest Parsing and Validation
Component Collection
Rust Application Component
External Binary Component
Model File Component
System Package Component
Packaging
Installation Script Generation
Command-Line Interface
Configuration Management
Error Handling and Recovery
Non-Functional Requirements
Performance
Reliability
Usability
Maintainability
Portability
Security
Scalability
External Interface Requirements
User Interfaces
Hardware Interfaces
Software Interfaces
Communications Interfaces
Enhanced Installation Features
Component Selection
Configuration Generation
Installation Modes
Dependency Management
v1.1 — Bill of Materials and Vulnerability Scanning
SBOM Generation
CBOM Generation
Vulnerability Scanning
v1.0 — Additional Component and Configuration Support
Config File Component
GitHub Release Source
Extended Install Section
Configuration Management Output
Nested Source Fields
Appendices
Example Manifest
Software Design Document
Introduction
Purpose
Scope
System Architecture
Architectural Style
High-Level Architecture
Component Descriptions
Detailed Design
Core Data Structures
Manifest Structure
Component Trait
Install Steps
Component Implementations
RustAppComponent
ExternalBinaryComponent
ModelFileComponent
ConfigFileComponent
GithubReleaseSource (ExternalBinaryComponent Variant)
Packaging Algorithm
Install Script Template
Interface Specifications
Component Plugin Interface
Design Decisions and Rationales
Why TOML for Manifests?
Why Build from Source on Air-Gapped System?
Why Component Trait Instead of Enums?
Why Generate Install Scripts Instead of Installing Directly?
Error Handling Strategy
Error Types
Error Recovery
Logging
Performance Considerations
Parallel Collection
Streaming Downloads
Caching
Security Considerations
Checksum Verification
Temporary File Security
No Arbitrary Code Execution
Testing Strategy
Unit Tests
Integration Tests
Platform Testing
Future Enhancements
Pre-built Binaries (v0.2)
Digital Signatures (v1.1)
Plugin System (v2.0)
Test Plan
Introduction
Purpose
Scope
Test Strategy
Test Levels
Test Types
Test Environment
Test Cases
Manifest Parsing (FR-DEPLOY-001 to FR-DEPLOY-005)
RustAppComponent (FR-DEPLOY-006 to FR-DEPLOY-010)
ExternalBinaryComponent (FR-DEPLOY-011 to FR-DEPLOY-014)
ModelFileComponent (FR-DEPLOY-015 to FR-DEPLOY-019)
Packaging (FR-DEPLOY-024 to FR-DEPLOY-029)
Install Script Generation (FR-DEPLOY-030 to FR-DEPLOY-036)
CLI Interface (FR-DEPLOY-037 to FR-DEPLOY-041)
Error Handling (FR-DEPLOY-045 to FR-DEPLOY-048)
End-to-End Workflows
Performance Tests
Security Tests
Enhanced Installation Feature Tests
Component Configuration Tests
System Package Component Tests
Installation Detection Tests
CLI Feature Tests
Configuration Management Tests
Error Handling Tests
External Interface Tests
Reliability NFR Tests
Usability NFR Tests
Maintainability NFR Tests
Portability NFR Tests
Security NFR Tests
Scalability NFR Tests
Test Execution
Unit Tests
Integration Tests
CI/CD Testing
Air-Gapped VM Testing
Test Metrics
Coverage Metrics
Quality Metrics
Performance Metrics
Test Schedule
Phase 1: Core Infrastructure
Phase 2: Built-in Components
Phase 3: Packaging
Phase 4: Install Scripts
Phase 5: CLI
Phase 6: Integration & System
Defect Management
Severity Levels
Defect Tracking
Test Deliverables
Test Code
Test Reports
Test Documentation
Risks and Mitigation
Approval
Future Test Scope
Requirements Traceability
Requirements to Tests Matrix
Requirements Coverage Statistics
Test Cases
Planning
Project Roadmap
v1.0.0 Release
Current Status
MVP Scope
Implementation Phases
Phase 1: Core Infrastructure
Phase 2: Built-in Components
Phase 3: Collection & Packaging
Phase 4: Installation Script Generation
Phase 5: CLI Interface
Phase 6: Testing & Documentation
Phase 7: Plugin System (Deferred to v1.1+)
Definition of Done
What’s NOT in MVP
After MVP
Key Documents
See Also
Progress Log
Implementation
API Reference
Planned Architecture
CLI Module (
cli
)
Manifest Module (
manifest
)
Rust App Module (
rust_app
)
Component Module (
component
)
Package Module (
package
)
Installer Module (
installer
)
Developer Resources
Future Enhancements
AirGap Deploy
Index
Edit on GitHub
Index