| title | ATLAS-0 |
|---|---|
| emoji | 🏠 |
| colorFrom | green |
| colorTo | yellow |
| sdk | docker |
| app_port | 8420 |
| pinned | false |
| license | mit |
| short_description | Room walkthrough in, evidence-backed safety brief out |
Upload one room walkthrough. Leave with a warm, evidence-backed Room Safety Brief.
A second pair of eyes on your room — before something tips, falls, spills, or blocks a path.
How it works · What it is · Quick start · API · Development · Roadmap
Important
Decision support, not safety certification. ATLAS-0 is intentionally honest about confidence, scan quality, and where the pipeline is still approximate. The design direction is Warm Trust: calm language, high contrast, visible uncertainty, and practical next steps — not demo theater or fake certainty.
|
A 20–60 second phone walkthrough of a real room. |
A Room Safety Brief: top actions, evidence frames, approximate locations, confidence, and fix-first recommendations. |
A downloadable PDF report to send to a landlord, partner, contractor, or care team. |
If ATLAS-0 becomes genuinely useful, it will be because it helps a person go from "this room feels unsafe or cluttered" to "here are the 3 things I should fix first."
| ✅ It is | 🚫 It is not |
|---|---|
|
|
Why someone reaches for it
- 🩺 Quick room triage — surface the objects most likely to fall, tip, spill, or break
- 🔧 Actionable output — what's wrong, why it matters, and what to do next
- 📎 Shareable evidence — a report for a landlord, partner, contractor, or insurer
- 🔁 Tiny home-care loop — one fix today, then a reason to rescan and watch the room get calmer
The current product slice
- Upload an image or room walkthrough video
- Guided capture: room label, audience mode, scan checklist, and optional browser-side Live Capture Coach
- Offline upload queuing and retry when a file is selected without connection
- Frame sampling and salient-region extraction
- Object labeling and approximate multi-view position estimates
- Hazard findings with severity · confidence · evidence frames · reasoning signals · recommendations
- Report-first review frontend at
/app - Bounded, deterministic "Ask this Safety Brief" answers
- PDF export and copyable share/action packets
- Privacy receipts: evidence inclusion and local blur/redaction previews
- Local room history, care plans, challenges, fixes, and before/after comparisons
- Operator quality, funnel, storage, worker, and eval-readiness signals
Current standing — strong vs. still rough
ATLAS-0 is a self-hosted beta product, not a broad demo shell. The spec: upload a walkthrough → get a trustworthy Safety Brief → fix one thing → optionally rescan to compare progress.
💪 Strong today
- First-run path: sample report, scan playbooks, audience modes, Room Mystery Mode, file preflight, capture guidance
- Live Capture Coach checks lighting, steadiness, duration, floor path, corners, and coverage in-browser before upload
- Durable job/artifact pipeline with detached-worker support and an IndexedDB retry queue for offline-selected files
- Brief surfaces top actions, Calm Score, confidence/uncertainty, evidence frames, fix difficulty, Field Notes, approximate evidence maps
- Privacy Receipt shows room label, evidence inclusion, local blur/redaction previews, retention posture, and delete controls
- Same-room rescans produce before/after deltas (score, hazards, compact evidence snapshots)
- Home Journal, Room Health Passport, Rituals, One Thing Today, Care Calendar, Fix Library, challenges, streaks, recaps — all local-first and accountless
- Trust Proof + operator views expose aggregate quality/funnel/storage/worker/eval signals without leaking private data
- Settings is a local control center: theme, accessibility, report/scan defaults, privacy clearing, backup/import, feedback, changelog
- Rust, Python, frontend smoke, deployment preflight, benchmark smoke, and API tests are in the local/CI quality gate
🚧 Still rough
- Upload-side grounding is approximate and evidence-backed, not survey-grade 3D reconstruction
- Live Capture Coach is lightweight browser guidance, not full real-time room understanding
- Offline covers the app shell, local journal/settings, and queued retry — not private reports or upload artifacts
- The eval corpus and feedback loops exist but need more real labeled scans before quality claims strengthen
- Still self-hosted beta — next is hosted operations, real onboarding, object-storage hardening, and a larger reviewed eval corpus
Warning
Known limitations — stated plainly.
- Spatial positions are estimated, not precisely measured.
- Reports are decision support, not professional safety certification.
- Weak scans degrade results — blur, darkness, short coverage, and low motion all reduce quality.
- Local redaction/blur affects share previews and copied wording; it does not mutate stored server artifacts.
- The PWA/offline shell intentionally avoids caching private upload, report, operator, and artifact routes.
- The scene view is secondary. The report is the product.
Prerequisites — Rust toolchain · Python 3.11+ · uv · one VLM path (local Ollama, OpenAI, or Anthropic).
git clone https://github.com/yashasviudayan-py/Atlas-0
cd Atlas-0
uv sync --extra dev --extra videoOptional provider extras
uv sync --extra dev --extra video --extra openai
uv sync --extra dev --extra video --extra claudeFor the default local path, start Ollama separately and make sure your configured model is available.
Run the upload-first product (the current product wedge — API + web app):
uv run python scripts/run_atlas.py --no-slamThen open http://localhost:8420/app — the report-first frontend where you
upload a scan and review the resulting hazard report.
Run the full stack (experimental Rust SLAM path)
uv run python scripts/run_atlas.py
# Useful variants
uv run python scripts/run_atlas.py --dev
uv run python scripts/run_atlas.py --config configs/default.toml
uv run python scripts/run_atlas.py --no-apiRun the production-like Docker stack
The closest local shape to a hosted beta: public API + upload worker as separate services with shared durable artifact storage.
cp .env.example .env
# Edit .env and replace ATLAS_API_ACCESS_TOKEN before exposing the stack.
docker compose -f docker/docker-compose.yml up --buildThen open http://localhost:8420/app. The Compose stack uses:
| Service | Role |
|---|---|
atlas-api |
FastAPI, static frontend, uploads, reports, metrics |
atlas-worker |
detached upload analysis |
atlas_data |
persisted job manifests, PDFs, evidence, replay assets |
object_store_fs |
pointer-based artifact storage |
ollama |
default local VLM provider |
Use Authorization: Bearer <ATLAS_API_ACCESS_TOKEN> for private upload/report
endpoints when loopback auth is disabled. Before exposing a hosted environment,
run the preflight (add --strict-warnings for stricter gates):
python scripts/check_deployment.pyThe fastest way to put ATLAS-0 online is the slim single-container web image
(docker/Dockerfile.web) — Python only, no Rust build
and no Ollama required. With no VLM provider reachable the pipeline falls back to
heuristic analysis, so the landing page and the built-in sample Safety Brief
work with zero configuration.
docker build -f docker/Dockerfile.web -t atlas0-web .
docker run -p 8420:8420 atlas0-webThen open http://localhost:8420/ — the bare host now redirects to the web
app at /app/.
Deploy to a PaaS (Render · Railway · Fly.io). Point the platform at
docker/Dockerfile.web. The container honors the platform-provided $PORT, and
GET /health is the readiness/liveness probe. No build command or start command
overrides are needed.
Important
ATLAS-0 is a long-running stateful container (background workers, WebSocket, on-disk job storage), so it needs a container host — Render, Railway, Fly.io, or any VPS/VM. Serverless frontend platforms (Vercel, Netlify, GitHub Pages) cannot run it: they have no persistent process, no writable disk, and function time limits shorter than one analysis job.
docker/Dockerfile.web ships without a VLM — uploads fall back to
heuristic labels with floor-level confidence. For a production demo with real
model-backed findings, use the bundled image
(docker/Dockerfile.web-vlm): same app plus a
local Ollama server with the moondream vision model baked in (no model
download at runtime).
docker build -f docker/Dockerfile.web-vlm -t atlas0-web-vlm .
docker run -p 8420:8420 --memory=4g atlas0-web-vlmSizing: ~4 GB image, give the container ≥ 4 GB RAM; CPU inference adds
roughly 10–60 s per upload depending on vCPU speed (the sample report is
pre-warmed at startup so visitors never wait on it). If Ollama ever fails
inside the container the app degrades to heuristics and /health reports a
degraded-provider warning — the site stays up.
Free hosting on Hugging Face Spaces: the repo-root Dockerfile
mirrors the VLM image for HF Spaces (which only builds from the root), and the
YAML block at the top of this README is the required Space metadata
(sdk: docker, app_port: 8420). Create a Docker Space on free CPU basic
hardware, add the repo as a remote, and push — the model bakes in during the
Space build, so no runtime downloads.
Alternatively, keep the slim image and point it at a managed VLM: set
ATLAS_VLM_PROVIDER=openai or claude plus the matching API key — no extra
memory needed and labels are higher quality than moondream.
| Variable | Default | Purpose |
|---|---|---|
PORT |
8420 |
Listen port (set automatically by most PaaS hosts). |
ATLAS_API_PUBLIC_DEMO |
false |
Open the visitor-facing upload/report endpoints to anonymous hosted requests so anyone can run their own scan. Operator tools (job listing, deletion, evaluation) stay private. The pre-built web image sets this true. |
ATLAS_API_ACCESS_TOKEN |
(unset) | Bearer token gating upload/report endpoints. A configured token always wins over ATLAS_API_PUBLIC_DEMO, so set a long random value to lock the instance down to a private beta. |
ATLAS_API_ENABLE_JOB_LISTING |
false |
Allow listing all jobs via GET /jobs. Keep false in public hosting. |
ATLAS_UPLOADS_WORKER_MODE |
in_process |
in_process for single-container hosting; external to run a detached worker (see Compose). |
ATLAS_UPLOADS_STORAGE_DIR |
/data/uploads |
Where job manifests and artifacts persist (mount a volume). |
ATLAS_UPLOADS_STRICT_STARTUP_CHECKS |
false |
Set true once storage and provider settings are final to fail fast on misconfiguration. |
ATLAS_VLM_PROVIDER |
ollama |
Optional: openai or anthropic for richer object labels (also set the matching API key and install the extra). |
Note
What works for anonymous visitors. The landing page, guided capture, journal/settings, and the public sample report always work with no token. For real uploads you choose the posture:
- Public demo (
ATLAS_API_PUBLIC_DEMO=true, the pre-built web image's default) — anyone can upload a room photo/video and get their own report; operator tools stay private. - Private beta (
ATLAS_API_ACCESS_TOKEN=…) — uploads require the token; paste it into Settings → operator access in the app. A token always wins over demo mode.
Running locally (loopback) uploads work without either setting.
Endpoints — product, operator, and experimental routes
| Method | Endpoint | Purpose |
|---|---|---|
POST |
/upload |
Upload an image or room walkthrough |
GET |
/jobs |
List upload jobs |
GET |
/jobs/{job_id} |
Fetch one job and its report payload |
POST |
/jobs/{job_id}/feedback |
Mark a finding useful, wrong, or duplicate |
POST |
/jobs/{job_id}/follow-up |
Mark findings resolved, monitoring, or ignored |
POST |
/jobs/{job_id}/evaluation |
Save human review / missed-hazard evaluation |
POST |
/jobs/{job_id}/eval-candidate |
Export review-ready eval candidates |
GET |
/reports/{job_id}.pdf |
Download the PDF report |
DELETE |
/jobs/{job_id} |
Delete a job and persisted artifacts |
GET |
/product/privacy |
Public retention/delete/privacy posture |
GET |
/product/upload-guidance |
Public upload limits and accepted media |
GET |
/product/trust-proof |
Privacy-safe aggregate quality signals |
POST |
/product/events |
Public product telemetry allowlist |
POST |
/product/waitlist |
Public beta waitlist capture |
GET |
/sample-report |
Built-in sample Safety Brief |
GET |
/operator/settings |
Token-protected operator diagnostics + beta inbox |
POST |
/operator/storage/prune |
Token-protected storage lifecycle pruning |
GET |
/health |
Runtime health and status |
GET |
/metrics |
Prometheus metrics |
POST |
/query |
Experimental — spatial query interface |
GET |
/objects |
Experimental — object listing |
GET |
/scene |
Experimental — scene snapshot |
WS |
/ws/risks |
Experimental — risk delta stream |
Required checks — everything that must pass before pushing
cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --all
env RUSTFLAGS='-D warnings' cargo test --all
ruff check python/ scripts/check_deployment.py scripts/run_upload_worker.py
ruff format --check python/
pytest python/tests/ -v
node --check frontend/js/api.js
node --check frontend/js/app.js
node --check frontend/js/upload.js
python -m py_compile scripts/check_deployment.py
python -m py_compile scripts/run_upload_worker.py
python scripts/check_deployment.py
python scripts/benchmark.py --iterations 1 --skip-vlmBenchmarks — the suite includes the committed sample walkthrough fixture so the upload/report path is regression-checked:
uv run python scripts/benchmark.py --skip-vlmcrates/ Rust crates — SLAM, physics, streaming, shared core
python/atlas/ Python API, VLM integration, world-model logic, utilities
frontend/ Report-first web UI
configs/ Runtime TOML configuration
scripts/ Process manager, benchmarks, support scripts
docs/ Architecture docs and development plan
data/ Sample walkthrough fixtures and expected output
tests/ Cross-language integration tests
The active roadmap lives in docs/DEVELOPMENT_PLAN.md. The current order of attack:
- Gather real beta scans and convert them into labeled eval cases
- Improve upload grounding beyond the current heuristic/multi-frame pipeline
- Harden hosted deployment — object storage, worker ops, artifact retention for production traffic
- Keep the report > the visualization — clearer evidence, stronger recommendations, better before/after verification
- Preserve Warm Trust — honest uncertainty, privacy controls, accessible UI, no safety-certification claims
MIT — see LICENSE.
Built with calm language, visible uncertainty, and a fix-first mindset. 🏠