blackLAB Factory

Local-first autonomous venture studio.
Persistent project memory, multi-department orchestration, 3D campus monitoring, and 24/7 recovery-aware loops.

What This Is

blackLAB Factory is a local AI company operating system.

It gives you:

• a control plane at http://127.0.0.1:8000
• a 3D campus at http://127.0.0.1:8000/console
• multi-department company runs
• persistent project memory across runs
• continuous autopilot loops with recovery logic

The goal is not to run one-off demos. The goal is to keep one project moving forward like a real AI company.

Core Concepts

Concept	Meaning
Project	A long-lived product/company effort with persistent memory and shared workspace
Run	One company work cycle that produces department artifacts and a final operator briefing
Loop	A long-running automation layer that keeps launching runs for the same project
Release Center	A manual packaging facility that creates a downloadable delivery bundle for the current project
Launch	Start one run manually
Autopilot	Start one loop that keeps improving the same project
Operator Chat	Natural-language control room for status, launch, stop, and defaults
3D Campus	Live 3D operations console for monitoring, runtime control, layout editing, and release packaging

Control Surfaces

Surface	Purpose
/	Executive overview of current project, recent runs, loops, event feed, and latest release status
/console	Primary 3D operations surface with runtime controls, Release Center, layout tools, and live event layer
/launch	Manual single-run execution
/autopilot	Continuous loop execution
/operator	Natural-language control channel
/runs	Ledger of all runs
/loops	Ledger of all loops
/settings	Runtime defaults, models, autonomy, parallelism

Quick Start

1. Install dependencies

uv sync --group dev
chmod +x ./blacklab.sh

2. Start the local control plane

./blacklab.sh

3. Open the product

./blacklab.sh open

Main URLs:

• Control plane: http://127.0.0.1:8000
• 3D Campus: http://127.0.0.1:8000/console

4. Stop it

# in the same terminal
Ctrl+C

Optional background mode:

./blacklab.sh start-bg
./blacklab.sh status
./blacklab.sh stop

Daily Workflow

1. Open /console if you want a visual live view of the company.
2. Open /launch if you want one controlled company cycle.
3. Open /autopilot if you want the same project to keep moving forward.
4. Open /runs to inspect one cycle in detail.
5. Open /loops to inspect long-running automation and recovery incidents.
6. Open /operator if you want to control the whole system in natural language.

Release Packaging

Release packaging is manual by design.

• it is not part of the normal run flow
• it is not part of the autopilot loop
• it only runs when the operator asks for a deliverable package

Use the Release Center in /console when you want to package the current project workspace into a downloadable bundle.

The dashboard overview also shows the latest release status and gives you a minimal Build Release / Download control surface.

Departments

The default company layout is:

• CEO
• Research
• Product
• Design
• Dev 1
• Dev 2
• Dev 3
• Growth
• Finance
• Validation
• Test Lab
• Quality Gate
• Board Review

Core departments focus on planning, design, and implementation.

Review departments focus on validation, testing, and final synthesis.

Release Center is not a normal production department. It is a support facility for final packaging and download delivery.

Persistent Project Memory

Every project gets its own directory under .factory/projects/<project-slug>/.

File	Purpose
project.md	Stable foundation context for the project
current.md	Latest authoritative context from the newest successful run
memory.md	Rolling memory of previous runs, decisions, risks, and next hints
workspace/	Shared project workspace for future implementation files
releases/	Download-ready release bundles, manifests, and archives

This means the next run does not start from zero.

The prompt stack is:

1. PROJECT FOUNDATION
2. PROJECT LIVE CONTEXT
3. PROJECT MEMORY

So the system can keep one product evolving over many runs.

Why this matters

Without a project layer, every run behaves like a separate demo.

With the project layer:

• the company remembers what it already decided
• the latest board-approved direction becomes the next starting point
• the same project can move from research to scope to implementation instead of restarting each time

24/7 Operation And Recovery

Autopilot is designed to keep one project moving, not just to repeat the same prompt.

When a run succeeds:

• the project memory is updated
• the latest context is refreshed
• the next loop iteration starts from the new state

When a run fails:

• the loop records a recovery incident
• Task Force, Rapid Response, and Recovery Ops guidance is created
• the loop can retry instead of dying immediately

Special handling exists for quota errors:

• usage limit is treated as a wait condition
• the system waits until retry time
• then resumes with a recovery cycle

Recovery model

The recovery path is intentionally different from a normal cycle.

• review lanes can be forced back to lightweight settings
• concurrency pressure can be reduced
• the next mission becomes a rescue mission instead of a full restart

This keeps the company aligned to the same project even after runtime failures.

Tech Stack

• Python 3.11+
• FastAPI
• Jinja2
• Typer
• Pydantic
• Uvicorn
• React 19
• Vite
• React Three Fiber / Drei / Three.js
• Codex CLI runtime integration

Development

Run tests:

.venv/bin/pytest -q

Run the backend directly:

.venv/bin/uvicorn blacklab_factory.web:create_app --factory --host 127.0.0.1 --port 8000

Build the frontend:

cd frontend
npm install
npm run build

Project Layout

src/blacklab_factory/     core runtime, orchestration, dashboard, storage
frontend/                 React-based 3D campus and console UI
config/company.yaml       department definitions and company defaults
.factory/                 runtime data, runs, loops, projects, releases, launchers, operator state
docs/                     architecture notes, references, screenshots
tests/                    backend and web test suite

Contributing And Collaboration

blackLAB Factory is being developed as a local-first open source system.

If you want to help:

• open an issue for bugs, usability gaps, or architectural problems
• open a pull request for focused improvements
• share reproduction steps, logs, screenshots, or project context when reporting runtime issues

If you want to collaborate more closely on the product direction:

• open a GitHub issue describing your use case, operating environment, and what you want to build with it
• include whether you are using it for solo work, an internal team workflow, or a client delivery pipeline

The most useful contributions right now are:

• runtime stability and recovery handling
• release packaging and delivery workflows
• console performance and 3D interaction quality
• documentation, onboarding, and reproducible local setup

Support

If blackLAB Factory is useful in your local workflow, you can support ongoing maintenance on GitHub Sponsors:

• https://github.com/sponsors/junexi0828

Advanced Notes

Launch vs Autopilot vs Operator Chat

• Launch creates one run and stops.
• Autopilot creates a loop that keeps launching runs.
• Operator Chat is the same control plane expressed in natural language.

Run vs Loop

• A run is one company work cycle.
• A loop is a persistent automation layer over many runs.

Use Runs to inspect one cycle.

Use Loops to inspect continuous project execution.

Related docs

• Stack Decision
• Market Map
• Orchestration References

---

Built by juns for blackLAB.