March 12, 2026 5 min read Python fork

dimos

Abstract

The Dimensional Framework

Technical Briefing: dimos Repository

The Problem

The repository contains 22 modules in circular import dependencies, with dimos/msgs/sensor_msgs/__init__.py, dimos/msgs/geometry_msgs/__init__.py, and dimos/core/module.py mutually reachable. Additionally, 155 modules depend on dimos/msgs/sensor_msgs/__init__.py and 138 on dimos/msgs/geometry_msgs/__init__.py, creating high-blast-radius hubs where changes ripple broadly. Max indentation depth reaches 6 in dimos/core/module.py, making control flow hard to follow. These structural issues increase cognitive load and risk unintended breakage when modifying core message or module systems.

What This Does

dimos is a collection of 4 self-contained projects totaling 1244 files: the core dimos system (958 files, 857 code files), examples (21 files), docker (22 files), and bin (21 files). It functions as an agentive operating system for physical robotics, enabling Python-based control of humanoids, quadrupeds, and drones without requiring ROS. Core capabilities include navigation and mapping (SLAM, dynamic obstacle avoidance), perception (detectors, 3D projections, VLMs, audio processing), agentive control via natural language, and spatial memory (spatio-temporal RAG, object localization). The codebase integrates React, Svelte, Flask, FastAPI, Transformers, YOLO, and vector stores, with Python (828 files) as the dominant language.

How It Is Wired

Execution starts from several entry points. main in bin/hooks/filter_commit_message.py:20 reaches 307 functions and is called from 1 place. start in dimos/agents/agent.py:75 reaches 400 functions with no other callers in the repo. run in dimos/manipulation/control/coordinator_client.py:459 reaches 195 functions, also called from nothing else. The internal call graph has 5272 resolved call edges. Vector3 is called from 187 places, publish from 110, Pose from 103. Key traced paths: main -> run_dimos [subprocess via subprocess.run]; start -> _connect [db via redis.Redis]; _call -> fn -> subscribe -> iterate_items -> _iter_items [db via conn.execute]. dimos/core/stream.py (36 functions, 9 classes) is central for observable streams, called from 57 files. dimos/msgs/geometry_msgs/Vector3.py (48 functions, 1 class) is called from 81 files. Circular imports affect dimos/core/module.py (95 importers, 11 imports, in a cycle) and message init files.

How To Use It

Setup: Clone via git clone https://github.com/moses-y/dimos. The presence of pyproject.toml indicates pip-based installation; package.json files indicate npm dependencies for web components. No ROS is required per the README.

Configuration: Environment variables and keys are loaded from docker/navigation/.env.hardware (evidenced as a committed .env file). The API server at dimos/web/dimos_interface/api/server.py uses allow_origins=["*"] with credentials enabled — this configuration should be reviewed. dimos/web/command-center-extension/package.json, vite.config.ts, and tsconfig.json configure the web extension.

Running it: The entry point start in dimos/agents/agent.py:75 initiates the agent system. For manipulation, run in dimos/manipulation/control/coordinator_client.py:459 is the designated start function. The README documents additional hardware-specific setups.

Real-World Use

A robotics team needs to deploy a navigation stack across a fleet of heterogeneous robots. Using dimos, they write Python agents that subscribe to lidar streams (via dimos/msgs/sensor_msgs), integrate YOLO-based perception, and issue motor commands through the control loop. The agent's spatial memory module queries the timeseries database (dimos/memory/timeseries/base.py) for localization data. The system runs natively on target hardware without ROS infrastructure, and the multi-agent architecture allows coordinating multiple robots from a single natural language prompt.

Code Health & Issues

CODE HEALTH AUDIT — 9 findings (0 critical, 4 high, 4 medium, 1 low), ranked by severity, confidence and production reach:

[HIGH] Pin third-party GitHub Actions to a commit SHA — .github/workflows: docker/login-action@v3, crazy-max/ghaction-github-runtime@v3, docker/setup-buildx-action@v3, docker/build-push-action@v6. A tag can move, so the action running with your token and secrets is whatever its owner last pushed.
[HIGH] Drop privileged mode and host networking — docker/dev/docker-compose.yaml: network_mode: host. Privileged hands every capability including direct device access; host networking removes the network boundary.
[HIGH] Remove the committed .env and rotate what it holds — docker/navigation/.env.hardware. A tracked .env is the most common route for working keys to reach a public clone; the app actually loads this file.
[HIGH] Replace the wildcard CORS origin with an explicit allow list — dimos/web/dimos_interface/api/server.py: allow_origins=["*"] together with credentials enabled. Any page on the internet can call the API with the browser's cookies attached.
[MEDIUM] Enable Dependabot or Renovate — 4 manifest(s), no update bot configured. Without a bot a published advisory sits unpatched.
[MEDIUM] Pin the container base image by digest — dimos/manipulation/grasping/docker_context/Dockerfile: nvidia/cuda:12.8.1-cudnn-devel-ubuntu22.04. An untagged base means today's build and last month's contain different libc and a different CVE set.
[MEDIUM] Gate pull requests on a dependency vulnerability scan — .github/workflows: no dependency scan in CI.
[MEDIUM] Add a non-root USER to the image — dimos/manipulation/grasping/docker_context/Dockerfile: no USER directive. A process running as root in the container is root against every mounted volume.
[LOW] Set timeout-minutes on the workflow jobs — .github/workflows/_docker-build-template.yml: 4 workflow(s) declare no job timeout.

Additionally, MEASURED FINDINGS from static analysis: 338 total (95 high, 239 medium, 4 low) including import cycle members, broad exception handling, deep nesting, hub modules, and file opened without context manager.

The Bottom Line

The repository delivers a functional agentive OS for physical robotics with genuine multi-hardware support and a working Python-first workflow. However, the circular import structure and hub modules create significant maintainability risk — changes to dimos/msgs/sensor_msgs or dimos/core/module affect 155+ and 138+ dependent modules respectively. The SDLC gaps (pinned Action SHAs, privileged Docker mode, committed .env, wildcard CORS) are actionable and should be addressed before production deployment. Teams needing rapid prototyping across diverse robot platforms will find value here, but those requiring long-term maintainability should budget refactor time for the import cycle and hub consolidation.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,244 files

Python828
Markdown79
JSON40
YAML25
TypeScript19
TSX13

ReactSvelteFlaskFastAPITailwindDockerTransformersYOLOVector store

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["dimos<br/>853 modules"] g1["examples<br/>6 modules"] g2["docker<br/>3 modules"] g3["bin<br/>2 modules"] g1 -->|16| g0

Module dependencies

The 10 most depended-upon modules of 865, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_os_msgs_sensor_msgs___init__["__init__"] n1_dimos_utils_logging_config["logging_config"] n2__msgs_geometry_msgs___init__["__init__"] n3_dimos_core_module["module"] n4_dimos_core_stream["stream"] n5_dimos_core_core["core"] n6_dimos_utils_data["data"] n7_dimos_core_blueprints["blueprints"] n8_dimos_core_transport["transport"] n9_dimos_types_timestamped["timestamped"] n7_dimos_core_blueprints --> n3_dimos_core_module n7_dimos_core_blueprints --> n4_dimos_core_stream n7_dimos_core_blueprints --> n8_dimos_core_transport n7_dimos_core_blueprints --> n1_dimos_utils_logging_config n3_dimos_core_module --> n5_dimos_core_core n3_dimos_core_module --> n4_dimos_core_stream n3_dimos_core_module --> n7_dimos_core_blueprints n3_dimos_core_module --> n8_dimos_core_transport n4_dimos_core_stream --> n1_dimos_utils_logging_config n8_dimos_core_transport --> n4_dimos_core_stream n9_dimos_types_timestamped --> n1_dimos_utils_logging_config n6_dimos_utils_data --> n1_dimos_utils_logging_config classDef cyc stroke:#ef4444,stroke-width:2px; class n0_os_msgs_sensor_msgs___init__,n2__msgs_geometry_msgs___init__,n3_dimos_core_module,n7_dimos_core_blueprints,n8_dimos_core_transport,n9_dimos_types_timestamped cyc;

Dependencies

19 of 36 declared dependencies are a major version behind. Resolved 36 of 36 against the registry.

Package	Declared	Latest	Behind
`@sveltejs/vite-plugin-svelte`	^3.0.1	7.3.0	4 major
`@types/node`	^22.3.0	26.2.0	4 major
`@vitejs/plugin-react`	^4.3.4	6.0.5	2 major
`typescript`	5.9.2	7.0.2	2 major
`vite`	^6.0.0	8.2.1	2 major
`@types/pako`	^2.0.4	3.0.0	1 major
`pako`	^2.1.0	3.0.1	1 major
`react-leaflet`	^4.2.1	5.0.0	1 major

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high5

medium4

low1

Pin third-party GitHub Actions to a commit SHAhigh8 occurrences

.github/workflows

docker/login-action@v3, crazy-max/ghaction-github-runtime@v3, docker/setup-buildx-action@v3, docker/build-push-action@v6

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh29 occurrences

python-multipart@0.0.6 CVE-2024-24762 (high) +17 more; fastapi@0.104.1 CVE-2024-24762 (high); jinja2@3.1.2 CVE-2024-56201 (high) +9 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Drop privileged mode and host networkinghigh2 occurrences

docker/dev/docker-compose.yaml

network_mode: host

privileged hands the container every capability including direct device access, which makes escaping to the host a documented one-liner, and host networking removes the network boundary so every port the container opens is open on the host.

Fix: Grant the specific capability the workload needs with cap_add, and publish ports explicitly.

Remove the committed .env and rotate what it holdshigh

docker/navigation/.env.hardware

A tracked .env is the most common route for a working key to reach a public clone, and it is the file the app actually loads, so the value is usually live.

Fix: git rm --cached the file, add it to .gitignore, rotate every credential it names, commit a .env.example with empty values.

Replace the wildcard CORS origin with an explicit allow listhigh

dimos/web/dimos_interface/api/server.py

allow_origins=["*"] together with credentials enabled

Any page on the internet can call the API with the browser's cookies attached, so a logged-in visitor to an unrelated site performs authenticated requests without knowing, and the wildcard combined with credentials is the exact configuration browsers refuse for that reason.

Fix: List the origins the API actually serves, and never pair a wildcard with credentials.

Enable Dependabot or Renovatemedium

4 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Pin the container base image by digestmedium

dimos/manipulation/grasping/docker_context/Dockerfile

nvidia/cuda:12.8.1-cudnn-devel-ubuntu22.04

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Add a non-root USER to the imagemedium

dimos/manipulation/grasping/docker_context/Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/_docker-build-template.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects