Create SDK applications and prepare DimOS contributor checkouts

.github/workflows/dimup.yml

@@ -29,13 +29,45 @@ jobs:
     steps:
       - uses: actions/checkout@v7
       - uses: astral-sh/setup-uv@v10.0.1
-      - name: Install shells for configuration tests
-        run: sudo apt-get update && sudo apt-get install -y zsh fish
-      - name: Installer and SDK packaging tests
+      - name: Install shell test tools
+        run: sudo apt-get update && sudo apt-get install -y zsh fish direnv
+      - name: Installer, packaging, and diagnostic tests
         env:
           PYTHONPATH: .
-        run: uv run --project installer --with pytest --with filelock --with setuptools --with pybind11 pytest --noconftest -c installer/pyproject.toml installer/src tests/packaging dimos/core/test_native_sources.py
+        run: uv run --project installer --with pytest --with filelock --with setuptools --with pybind11 pytest --noconftest -c installer/pyproject.toml installer/src tests/packaging dimos/core/test_native_sources.py dimos/cli/test_doctor.py
       - name: Type check dimup
         env:
           MYPYPATH: installer/src
-        run: uv run --project installer --with mypy mypy --strict --follow-imports=silent installer/src/dimup/cli.py installer/src/dimup/process.py installer/src/dimup/setup.py installer/src/dimup/shell.py
+        run: uv run --project installer --with mypy mypy --strict --follow-imports=silent installer/src/dimup/cli.py installer/src/dimup/project.py installer/src/dimup/process.py installer/src/dimup/setup.py installer/src/dimup/sdk.py installer/src/dimup/shell.py installer/src/dimup/development.py
+  journey:
+    needs: unit
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, ubuntu-24.04, macos-14]
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@v7
+      - name: Bootstrap from source and prepare machine
+        env:
+          DIMUP_REF: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: |
+          export PATH="$HOME/.local/bin:$HOME/.cargo/bin:/opt/homebrew/bin:$PATH"
+          bash installer/bootstrap.sh
+          export PATH="$(uv tool dir --bin):$PATH"
+          echo "$(uv tool dir --bin)" >> "$GITHUB_PATH"
+          echo "$HOME/.local/bin" >> "$GITHUB_PATH"
+          echo "$HOME/.cargo/bin" >> "$GITHUB_PATH"
+          dimup setup
+      - name: Create applications, prepare contributors, and run
+        env:
+          SDK_REF: ${{ github.event.pull_request.head.sha || github.sha }}
+        run: python3 installer/run/acceptance --ref "$SDK_REF" --results "$RUNNER_TEMP/dimup-results" --contributor --native
+      - uses: actions/upload-artifact@v7
+        if: always()
+        with:
+          name: dimup-${{ matrix.os }}
+          path: |
+            ${{ runner.temp }}/dimup-results/
+            ~/.local/state/dimup/setup.log

.gitignore

@@ -100,3 +100,6 @@ site/
 
 # Optuna study store, written by the relocalization eval (see lidar/eval.md)
 optuna.db
+
+# Local installer validation artifacts
+/.dimos/

CONTRIBUTING.md

@@ -51,7 +51,7 @@ We want people to use Dimensional, learn it, and help us build it. You do not ne
 Browse [open issues labeled](https://github.com/dimensionalOS/dimos/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) `good first issue`. These are scoped tasks that maintainers have marked as approachable for newcomers. Pick one, read the description, and comment if you want to work on it or need clarification. Maintainers are happy to point you in the right direction.
 
 **Get set up.**
-Follow [AGENTS.md](AGENTS.md) for install (`uv sync --extra all`), running blueprints in simulation or replay, and the test workflow (`uv run pytest`). Most changes can be developed and validated without a physical robot.
+Follow the [contributor setup guide](docs/installation/installer.md#work-on-dimos-itself): prepare your machine with the curl bootstrap, then run `dimup dev dimos --ref feat/dimup-release` while testing this PR. It clones dimOS, installs the editable environment and development tools, and installs commit hooks. See [AGENTS.md](AGENTS.md) for running blueprints and the test workflow. Most changes can be developed and validated without a physical robot.
 
 **This still applies to you.**
 The [critical rule](#the-critical-rule) and [AI policy](AI_POLICY.md) apply to every outside contribution, including yours. Use AI tools if they help you learn the codebase, but understand what you submit. Link your PR to the issue you are working on.

README.md

@@ -137,55 +137,42 @@ Dimensional is agent native -- "vibecode" your robots in natural language and bu
 
 # Installation
 
-## Interactive Install
+## Test a dimOS SDK application
 
-```sh skip
-curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/main/scripts/install.sh | bash
-```
-
-> See [`scripts/install.sh --help`](scripts/install.sh) for non-interactive and advanced options.
-
-## Manual System Install
-
-To set up your system dependencies, follow one of these guides:
-
-- 🟩 [Ubuntu 22.04 / 24.04](docs/installation/ubuntu.md)
-- 🟩 [NixOS / General Linux](docs/installation/nix.md)
-- 🟧 [macOS](docs/installation/osx.md)
-
-> Full system requirements, tested configs, and dependency tiers: [docs/requirements.md](docs/requirements.md)
-
-## Python Install
-
-### Quickstart
+Test the current installer PR on Ubuntu 22.04/24.04 x86_64 or Apple Silicon macOS
+14+. Use both branch overrides below until the changes merge:
 
 ```bash
-uv venv --python "3.12"
-source .venv/bin/activate
-uv pip install 'dimos[base,unitree]'
-
-# Replay a recorded quadruped session (no hardware needed)
-# NOTE: First run will show a black rerun window while ~75 MB downloads from LFS
-dimos --replay run unitree-go2
+curl -fsSL https://raw.githubusercontent.com/dimensionalOS/dimos/feat/dimup-release/installer/bootstrap.sh \
+  | DIMUP_REF=feat/dimup-release bash
+dimup init my-robot --ref feat/dimup-release
+cd my-robot
+source .dimos/activate.sh
+dimos run my-robot.demo
 ```
 
-```bash
-# Install with simulation support
-uv pip install 'dimos[base,unitree,sim]'
+The bootstrap installs `dimup` and prepares the machine; follow its printed PATH
+instruction before running `dimup init`. That command creates an
+editable application pinned to the resolved SDK commit from the PR branch. Its two-module
+example generates images and prints their dimensions, without hardware or datasets.
+Edit `src/my_robot/demo.py`, run `pytest`, and rerun the blueprint.
 
-# Run quadruped in MuJoCo simulation
-dimos --simulation run unitree-go2
+See the [installation guide](docs/installation/installer.md) for machine setup,
+SDK revision selection, cloning applications, diagnostics, and optional direnv.
 
-# Run humanoid in simulation
-dimos --simulation run unitree-g1-sim
-```
+To work on dimOS itself after the bootstrap:
 
 ```bash
-# Control a real robot (Unitree quadruped over WebRTC)
-export ROBOT_IP=<YOUR_ROBOT_IP>
-dimos run unitree-go2
+dimup dev dimos --ref feat/dimup-release
+cd dimos
+source .dimos/activate.sh
+dimos doctor
+git switch -c feat/my-change
 ```
 
+This prepares an editable contributor checkout with test/lint tools and commit
+hooks. See the [contributor setup procedure](docs/installation/installer.md#work-on-dimos-itself).
+
 # Featured Runfiles
 
 | Run command | What it does |

dimos/cli/doctor.py

@@ -0,0 +1,179 @@
+# Copyright 2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Read-only diagnostics for a DimOS application or contributor checkout."""
+
+import argparse
+import json
+from pathlib import Path
+import shutil
+import subprocess
+import sys
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    import tomli as tomllib
+
+
+def project_root(path: Path) -> Path:
+    for root in (path.resolve(), *path.resolve().parents):
+        manifest = root / "pyproject.toml"
+        if manifest.is_file():
+            config = tomllib.loads(manifest.read_text())
+            if "dimos" in config.get("tool", {}).get("uv", {}).get("sources", {}) or (
+                config.get("project", {}).get("name") == "dimos" and (root / "dimos").is_dir()
+            ):
+                return root
+    raise ValueError(
+        "No DimOS project found. Run inside an application created by dimup init or a checkout prepared by dimup dev."
+    )
+
+
+def probe(python: Path, script: str, *args: str, cwd: Path) -> tuple[bool, str]:
+    try:
+        result = subprocess.run(
+            [str(python), "-I", "-c", script, *args],
+            capture_output=True,
+            text=True,
+            timeout=45,
+            check=False,
+            cwd=cwd,
+        )
+    except (OSError, subprocess.TimeoutExpired) as error:
+        return False, str(error)
+    if result.returncode:
+        return False, (result.stderr or result.stdout).strip()[-1500:]
+    return True, result.stdout.strip()
+
+
+METADATA_CHECK = """import importlib.metadata as m, json, sys
+from pathlib import Path
+app = m.distribution(sys.argv[1])
+sdk = m.distribution("dimos")
+print(json.dumps({
+    "editable": json.loads(app.read_text("direct_url.json") or "{}"),
+    "sdk": json.loads(sdk.read_text("direct_url.json") or "{}"),
+    "entries": [e.name for e in app.entry_points if e.group == "dimos.blueprints"],
+    "version": sdk.version,
+    "source": str(Path(__import__("dimos").__file__).resolve()),
+}))
+"""
+LIBRARY_CHECK = """import ctypes
+from ctypes.util import find_library
+import numpy as np
+import sqlite3, sqlite_vec
+from turbojpeg import TurboJPEG
+import zenoh, lcm
+with sqlite3.connect(":memory:") as connection:
+    if not hasattr(connection, "enable_load_extension"):
+        raise RuntimeError(
+            "Python lacks SQLite extension loading. Recreate .venv with uv-managed Python: "
+            "uv venv --clear --managed-python --python 3.12 && uv sync --locked"
+        )
+    connection.enable_load_extension(True)
+    sqlite_vec.load(connection)
+    connection.enable_load_extension(False)
+    connection.execute("SELECT vec_version()").fetchone()
+for name in ("portaudio", "sndfile"):
+    path = find_library(name)
+    if not path:
+        raise RuntimeError(f"Missing host library: {name}; run dimup setup")
+    ctypes.CDLL(path)
+codec = TurboJPEG()
+image = np.zeros((8, 8, 3), dtype=np.uint8)
+assert codec.decode(codec.encode(image)).shape == image.shape
+"""
+
+
+def diagnose(root: Path) -> list[tuple[bool, str, str]]:
+    manifest = tomllib.loads((root / "pyproject.toml").read_text())
+    name = manifest["project"]["name"]
+    contributor = name == "dimos"
+    python = root / ".venv/bin/python"
+    results = [
+        (
+            Path(sys.prefix).resolve() == (root / ".venv").resolve(),
+            "Active environment",
+            "source .dimos/activate.sh selects this project's interpreter",
+        )
+    ]
+    if not python.is_file():
+        return [*results, (False, "Application environment", "Run uv sync --locked")]
+    ok, detail = probe(python, METADATA_CHECK, name, cwd=root)
+    if ok:
+        metadata: dict[str, Any] = json.loads(detail)
+        app = metadata["editable"]
+        editable = app.get("dir_info", {}).get("editable") and app.get("url") == root.as_uri()
+        if contributor:
+            source = metadata.get("source")
+            results.append(
+                (
+                    bool(editable) and source == str(root / "dimos/__init__.py"),
+                    "Editable DimOS checkout",
+                    f"Expected {root}; imported {source}. Run uv sync --locked if they differ",
+                )
+            )
+        else:
+            results.append(
+                (
+                    bool(editable),
+                    "Editable application",
+                    "Run uv sync --locked to install this application",
+                )
+            )
+            results.append(
+                (
+                    bool(metadata["entries"]),
+                    "Blueprint registration",
+                    ", ".join(metadata["entries"]) or "Run uv sync to refresh entry points",
+                )
+            )
+            expected = manifest["tool"]["uv"]["sources"]["dimos"]["rev"]
+            commit = metadata["sdk"].get("vcs_info", {}).get("commit_id")
+            results.append(
+                (
+                    commit == expected,
+                    "SDK revision",
+                    f"Expected {expected}; installed {commit}. Run uv sync --locked if they differ",
+                )
+            )
+    else:
+        results.append((False, "Installed metadata", f"{detail}\nRun uv sync --locked"))
+    for tool in ("uv", "cargo", "nix", "git"):
+        found = shutil.which(tool)
+        results.append(
+            (found is not None, tool, found or "Run dimup setup, then activate the project")
+        )
+    ok, detail = probe(python, LIBRARY_CHECK, cwd=root)
+    results.append((ok, "Native libraries and image codec", detail or "Image round trip passed"))
+    return results
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="dimos doctor", description=__doc__)
+    parser.add_argument("--project-dir", type=Path, default=Path.cwd())
+    args = parser.parse_args(argv)
+    try:
+        results = diagnose(project_root(args.project_dir))
+    except (OSError, ValueError, KeyError, TypeError) as error:
+        results = [(False, "Application", str(error))]
+    for ok, label, detail in results:
+        print(f"{'PASS' if ok else 'FAIL'}  {label}: {detail}")
+    return int(any(not ok for ok, _, _ in results))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

dimos/cli/entrypoint.py

@@ -0,0 +1,24 @@
+# Copyright 2026 Dimensional Inc.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Keep diagnostics accessible before importing the robotics runtime."""
+
+from importlib import import_module
+import sys
+
+
+def cli_main() -> None:
+    if sys.argv[1:2] == ["doctor"]:
+        raise SystemExit(import_module("dimos.cli.doctor").main(sys.argv[2:]))
+    import_module("dimos.cli.dimos").cli_main()