Skip to content

Self-improving AI Employees for everyone

refactor(paths): unify DATA_DIR resolution; dev vs daemon state split

trohitgfc9bcd24d488
diff --git a/.env b/.env
new file mode 100644
index 00000000..ebfd5047
--- /dev/null
+++ b/.env
@@ -0,0 +1,167 @@
+# Service Ports (used by start.js, vite, and docker-compose)
+VITE_CLIENT_PORT=3000
+PYTHON_BACKEND_PORT=3010
+NODEJS_EXECUTOR_PORT=3020
+WHATSAPP_RPC_PORT=9400
+REDIS_PORT=6379
+
+# Server Configuration
+HOST=127.0.0.1
+PORT=3010
+DEBUG=false
+WORKERS=1
+
+# Security (Development keys - MUST CHANGE FOR PRODUCTION)
+SECRET_KEY=dev-secret-key-12345678901234567890123456789012
+API_KEY_ENCRYPTION_KEY=dev-encryption-key-12345678901234567890123456
+
+# Authentication
+# VITE_AUTH_ENABLED: "true" (require login) or "false" (bypass authentication)
+VITE_AUTH_ENABLED=false
+# AUTH_MODE: "single" (local deploy - first user is owner) or "multi" (cloud - open registration)
+AUTH_MODE=single
+JWT_SECRET_KEY=dev-jwt-secret-key-12345678901234567890
+JWT_EXPIRE_MINUTES=10080
+JWT_COOKIE_NAME=machina_token
+JWT_COOKIE_SECURE=false
+JWT_COOKIE_SAMESITE=lax
+
+# CORS Configuration - Allow all common dev ports
+CORS_ORIGINS=["http://localhost:3000","http://localhost:3001","http://localhost:3002","http://localhost:3003","http://localhost:3004","http://localhost:3005","http://localhost:3006","http://127.0.0.1:3000","http://127.0.0.1:3001","http://127.0.0.1:3002","http://127.0.0.1:3003","http://127.0.0.1:3004","http://127.0.0.1:3005","http://127.0.0.1:3006","http://localhost:5173"]
+
+# Database Configuration
+# SQLite DB filename. Resolved under DATA_DIR by
+# ``Settings._resolve_under_data`` — same pattern as ``temporal.db``
+# and ``credentials.db`` so dev mode's DATA_DIR=.machina moves all
+# three together. The SQLAlchemy URL is composed at runtime by
+# ``Settings.database_url`` (sqlite+aiosqlite:///<abspath>).
+WORKFLOW_DB_FILENAME=workflow.db
+DATABASE_ECHO=false
+DATABASE_POOL_SIZE=5
+DATABASE_MAX_OVERFLOW=10
+
+# Cache Configuration (Disabled for development)
+REDIS_ENABLED=false
+CACHE_TTL=300
+
+# Temporal Configuration
+# Enable for durable workflow execution with automatic retries.
+# Backed by ``temporal server start-dev`` against a SQLite db at
+# ``TEMPORAL_SQLITE_PATH``. The official ``temporal`` CLI is downloaded
+# by pooch from https://temporal.download/cli/archive/latest on
+# ``machina build`` (or first ``machina start`` if build was skipped).
+TEMPORAL_ENABLED=true
+TEMPORAL_SERVER_ADDRESS=localhost:7233
+TEMPORAL_NAMESPACE=default
+TEMPORAL_TASK_QUEUE=machina-tasks
+TEMPORAL_PER_TYPE_DISPATCH=true
+TEMPORAL_AGENT_WORKFLOW_ENABLED=true
+# gRPC frontend port the CLI dev server binds (``--port``). Default per
+# https://docs.temporal.io/references/configuration.
+TEMPORAL_FRONTEND_GRPC_PORT=7233
+# Web UI port (``--ui-port``). ``temporal server start-dev`` defaults
+# this to ``--port + 1000``; we override to 8080 to match the
+# historical MachinaOS port (kept for muscle memory + bookmarks).
+# Browse to http://<host>:<TEMPORAL_UI_PORT>/.
+TEMPORAL_UI_PORT=8080
+# SQLite db file ``temporal server start-dev --db-filename`` opens.
+# Relative to DATA_DIR (= ~/.machina/) unless absolute. Flat under
+# DATA_DIR like ``credentials.db`` / ``workflow.db``. History is
+# always preserved across restarts (Temporal UI keeps showing every
+# workflow that ever ran); see ``TEMPORAL_TERMINATE_RUNNING_ON_STARTUP``
+# below for the resumption knob.
+TEMPORAL_SQLITE_PATH=temporal.db
+# On server boot, terminate every workflow still in ``Running`` state.
+# History is preserved (workflows show as ``Terminated`` in the UI,
+# NOT deleted) but resumption is disabled, because MachinaOS's
+# ``DeploymentManager`` has no boot-time reconcile against Temporal
+# Visibility yet — resumed workflows would otherwise keep executing
+# but be invisible to the MachinaOS UI. Flip to ``false`` once the
+# reconcile lands to re-enable durable resumption.
+TEMPORAL_TERMINATE_RUNNING_ON_STARTUP=true
+# Graceful shutdown window for the Temporal child process.
+TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS=30
+# Supervisor readiness-probe window. The CLI binary may need to
+# download (~114 MB zip) on first ``machina start`` if ``machina build``
+# didn't pre-cache it.
+TEMPORAL_SERVER_READY_TIMEOUT_SECONDS=120
+
+# Wave 12 event framework. ``true`` (default) routes trigger events
+# through TriggerListenerWorkflow + Temporal Signal fan-out for the
+# 8 canary-registered trigger types (webhook, chat, task, telegram,
+# whatsapp, gmail, cron, email). Flip to ``false`` to roll back to
+# the legacy event_waiter path -- see docs-internal/event_framework.md.
+EVENT_FRAMEWORK_ENABLED=true
+
+# Memory compaction. ``true`` (default) auto-compacts agent
+# conversation memory when cumulative tokens exceed the model's
+# context-window threshold. Per-session overrides via the UI.
+COMPACTION_ENABLED=true
+
+# Dead-letter queue for failed workflow executions. Off by default.
+DLQ_ENABLED=false
+
+# Data directory (base for all persistent storage: DBs, workspaces,
+# workflows, claude state). User-home rooted by default — same
+# convention claude code itself uses (`~/.claude/`), Stripe
+# (`~/.config/stripe/`), ngrok (`~/.ngrok2/`). Survives `rm -rf` of
+# the repo and lets multiple checkouts share state.
+#
+# Resolution rules (`server/core/paths.py::machina_root`):
+# - `~/...` → user home (cross-platform via Path.expanduser)
+# - absolute → used verbatim
+# - relative → resolved under repo root (back-compat)
+#
+# Set to `.machina` (or `data`) if you want repo-local behaviour
+# instead. Pre-cutover layouts (`<repo>/data/`, `<repo>/workflows/`)
+# do NOT auto-migrate — see `server/core/paths.py` for the manual
+# `mv` checklist if you're upgrading from an older release.
+DATA_DIR=~/.machina
+
+# Per-workflow workspace (nodes save files here, resolved under DATA_DIR)
+WORKSPACE_BASE_DIR=workspaces
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FORMAT=text
+
+# Rate Limiting (Relaxed for development)
+RATE_LIMIT_ENABLED=false
+RATE_LIMIT_REQUESTS=1000
+RATE_LIMIT_WINDOW=60
+
+# Service Timeouts (Extended for debugging)
+AI_TIMEOUT=60
+AI_MAX_RETRIES=1
+AI_RETRY_DELAY=0.5
+
+MAPS_TIMEOUT=30
+
+# Health Check
+HEALTH_CHECK_INTERVAL=60
+
+# Cleanup Configuration (for long-running daemon)
+CLEANUP_ENABLED=true
+CLEANUP_INTERVAL=3600
+CLEANUP_LOGS_MAX_COUNT=1000
+CLEANUP_CACHE_MAX_AGE_HOURS=24
+
+# Feature Toggles
+WS_LOGGING_ENABLED=true
+
+# Gunicorn Configuration (for production deployment)
+# GUNICORN_TIMEOUT=120
+# GUNICORN_GRACEFUL_TIMEOUT=30
+# GUNICORN_KEEPALIVE=5
+# GUNICORN_MAX_REQUESTS=10000
+# GUNICORN_MAX_REQUESTS_JITTER=1000
+
+# WebSocket Configuration (For remote Android device connections)
+WEBSOCKET_URL=wss://relay.zeenie.xyz/ws
+WEBSOCKET_API_KEY=
+
+# AI Proxy Configuration (Ollama-style proxy for Claude Code CLI)
+# Default port for AI proxy servers (e.g., Ollama, Claude Code CLI proxy)
+AI_PROXY_DEFAULT_PORT=11434
+
+
diff --git a/.env.dev b/.env.dev
new file mode 100644
index 00000000..5c63eabb
--- /dev/null
+++ b/.env.dev
@@ -0,0 +1,16 @@
+# Dev-mode env overrides — layered on top of ``.env.template`` and
+# ``.env`` by ``machina dev`` (only). The ``machina start`` /
+# ``machina daemon`` paths never load this file, so production-style
+# runs keep the ``.env.template`` defaults (DATA_DIR=~/.machina).
+#
+# Loaded by ``cli.config.load_dev_overrides`` via ``os.environ.setdefault``
+# so an explicit shell override (``DATA_DIR=/foo machina dev``) still
+# wins. Committed to git as the canonical dev convention — every
+# checkout's ``machina dev`` lands state in the same place.
+
+# Per-checkout state under <repo>/.machina/ (resolved as a relative
+# path under ``project_root()`` by ``core.paths.machina_root``).
+# Multiple worktrees on the same machine each get their own clean
+# DB / workspaces / temporal history; ``rm -rf`` of the worktree
+# wipes the runtime state alongside the source.
+DATA_DIR=.machina
diff --git a/.env.template b/.env.template
index 615410e8..ebfd5047 100644
--- a/.env.template
+++ b/.env.template
@@ -30,11 +30,12 @@ JWT_COOKIE_SAMESITE=lax
CORS_ORIGINS=["http://localhost:3000","http://localhost:3001","http://localhost:3002","http://localhost:3003","http://localhost:3004","http://localhost:3005","http://localhost:3006","http://127.0.0.1:3000","http://127.0.0.1:3001","http://127.0.0.1:3002","http://127.0.0.1:3003","http://127.0.0.1:3004","http://127.0.0.1:3005","http://127.0.0.1:3006","http://localhost:5173"]
# Database Configuration
-# SQLite DB file. ``~`` expands cross-platform at Settings load time
-# (Path.expanduser → ``$HOME`` on POSIX, ``%USERPROFILE%`` on Windows).
-# Keep this in sync with DATA_DIR below — both should live under the
-# same root.
-DATABASE_URL=sqlite+aiosqlite:///~/.machina/workflow.db
+# SQLite DB filename. Resolved under DATA_DIR by
+# ``Settings._resolve_under_data`` — same pattern as ``temporal.db``
+# and ``credentials.db`` so dev mode's DATA_DIR=.machina moves all
+# three together. The SQLAlchemy URL is composed at runtime by
+# ``Settings.database_url`` (sqlite+aiosqlite:///<abspath>).
+WORKFLOW_DB_FILENAME=workflow.db
DATABASE_ECHO=false
DATABASE_POOL_SIZE=5
DATABASE_MAX_OVERFLOW=10
diff --git a/.gitignore b/.gitignore
index 66abbfcb..25056bc9 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,15 +21,10 @@ package-lock.json
# =============================================================================
# SECURITY - Credentials and Secrets (NEVER COMMIT)
# =============================================================================
-# Environment variables (contain API keys, secrets)
-.env
-.env.*
-!.env.template
-!.env.example
-server/.env
-server/.env.*
-!server/.env.template
-!server/.env.example
+# Env files are committed — they hold only ports, paths, feature flags,
+# and other non-sensitive config. Credentials live in the encrypted
+# ``credentials.db`` (Fernet + PBKDF2 via ``server/core/encryption.py``),
+# never in env files.
# API Keys and Credentials
**/credentials.json
diff --git a/.npmignore b/.npmignore
index eb9193e3..4b1e85cc 100644
--- a/.npmignore
+++ b/.npmignore
@@ -7,10 +7,10 @@
.gitignore
.github/
-# Environment & secrets
-.env
-.env.*
-!.env.template
+# Env files ship with the package — they hold only non-sensitive config
+# (ports, paths, feature flags). Credentials live in the encrypted
+# ``credentials.db`` (Fernet + PBKDF2 via server/core/encryption.py),
+# never in env files. Matches the .gitignore policy.
# Database files
*.db
diff --git a/cli/commands/dev.py b/cli/commands/dev.py
index 24d64152..b55f2071 100644
--- a/cli/commands/dev.py
+++ b/cli/commands/dev.py
@@ -21,6 +21,7 @@ import typer
from cli._common import build_backend_spec, free_all_ports, preflight
from cli.colors import console
+from cli.config import load_dev_overrides
from cli.platform_ import (
node_modules_dir,
platform_name,
@@ -32,10 +33,9 @@ from cli.commands._temporal_specs import temporal_specs
def _has_vite(root: Path) -> bool:
- return (
- (node_modules_dir(root) / "vite").exists()
- or (root / "client" / "node_modules" / "vite").exists()
- )
+ return (node_modules_dir(root) / "vite").exists() or (
+ root / "client" / "node_modules" / "vite"
+ ).exists()
def _clear_vite_cache(root: Path) -> None:
@@ -73,9 +73,18 @@ def _build_specs(root: Path, cfg, *, daemon: bool, use_vite: bool) -> list[Servi
def dev_command(
daemon: bool = typer.Option(
- False, "--daemon", help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",
+ False,
+ "--daemon",
+ help="Bind backend to 0.0.0.0 instead of 127.0.0.1.",
),
) -> None:
+ # Layer ``.env.dev`` (committed) on top of ``.env.template`` + ``.env``
+ # so dev state lands at ``<repo>/.machina/`` (per-checkout) instead
+ # of ``~/.machina/`` (user home). Called BEFORE ``preflight()`` so
+ # ``load_config``'s ``setdefault`` pass sees the dev values already
+ # in ``os.environ``. ``machina start`` / ``machina daemon`` skip
+ # this hook, falling through to the ``.env.template`` defaults.
+ load_dev_overrides()
cfg, root = preflight()
os.environ.setdefault("PYTHONUTF8", "1")
@@ -83,7 +92,9 @@ def dev_command(
console.print("\n[bold]=== MachinaOS Starting ===[/]\n")
console.print(f"Platform: {platform_name()}")
- console.print(f"Mode: {'Daemon (uvicorn)' if daemon else 'Development (uvicorn)'}")
+ console.print(
+ f"Mode: {'Daemon (uvicorn)' if daemon else 'Development (uvicorn)'}"
+ )
console.print(f"Ports: {', '.join(str(p) for p in cfg.all_ports)}")
console.log("Freeing ports...")
diff --git a/cli/config.py b/cli/config.py
index cccc26b8..a928da4c 100644
--- a/cli/config.py
+++ b/cli/config.py
@@ -1,16 +1,25 @@
-"""Project configuration -- typed view over ``.env`` / ``.env.template``.
-
-Stdlib-only env-var loader. ``.env.template`` ships with every install
-and is the canonical source of defaults; ``.env`` (created by
-``scripts/postinstall.js`` on ``npm install -g machinaos``) layers user
-overrides on top; ``os.environ`` wins over both at the call site.
-
-Merged values are pushed into ``os.environ`` so downstream consumers
-that read ``os.environ`` directly see the same view as this module.
-
-No Python-side hardcoded defaults: ``.env.template`` is the single
-source of truth. If the template is missing (broken install), we error
-out loudly with a remediation hint rather than silently substituting
+"""Project configuration -- typed view over ``.env.dev`` / ``.env`` / ``.env.template``.
+
+Stdlib-only env-var loader. Three env files, lowest precedence first:
+
+ 1. ``.env.template`` — canonical production defaults. Ships with every
+ install. ``DATA_DIR=~/.machina`` (user home) is the daemon
+ behaviour: ``machina start`` / ``machina daemon`` use these.
+ 2. ``.env`` — user overrides (created by ``scripts/postinstall.js`` on
+ ``npm install -g machinaos``). Gitignored.
+ 3. ``.env.dev`` — dev-mode overrides. Loaded ONLY by ``machina dev``
+ via :func:`load_dev_overrides`. Pins ``DATA_DIR=.machina`` so
+ per-checkout dev state lives at ``<repo>/.machina/`` instead of
+ ``~/.machina/``. Committed to git.
+
+Process env (``os.environ``) wins over all three. Merged file values
+are pushed into ``os.environ`` via ``setdefault`` so downstream
+consumers that read ``os.environ`` directly see the same view as this
+module.
+
+No Python-side hardcoded defaults: env files are the single source of
+truth. If ``.env.template`` is missing (broken install), we error out
+loudly with a remediation hint rather than silently substituting
duplicate hardcoded values that drift from the shipped template.
"""
@@ -94,6 +103,27 @@ class Config:
]
+def load_dev_overrides(root: Path | None = None) -> None:
+ """Layer ``.env.dev`` on top of ``.env.template`` + ``.env``.
+
+ Called by ``machina dev`` BEFORE :func:`load_config` so dev-only env
+ vars (notably ``DATA_DIR=.machina``, the per-checkout dev state
+ root) land in ``os.environ`` first. ``load_config`` then sees them
+ via its own ``setdefault`` pass and skips its template fallbacks.
+
+ Uses ``setdefault`` so an explicit shell override
+ (``DATA_DIR=/foo machina dev``) still wins. Missing ``.env.dev``
+ file is a no-op — production-style invocations never trigger this.
+
+ The daemon path (``machina start`` / ``machina daemon``) does not
+ call this, so daemon installs keep the ``.env.template`` default
+ of ``DATA_DIR=~/.machina``.
+ """
+ root = root or project_root()
+ for key, value in _load_env_file(root / ".env.dev").items():
+ os.environ.setdefault(key, value)
+
+
@lru_cache(maxsize=1)
def load_config(root: Path | None = None) -> Config:
"""Load + merge ``.env.template`` (baseline) and ``.env`` (overrides).
diff --git a/server/core/config.py b/server/core/config.py
index 59983527..5728e321 100644
--- a/server/core/config.py
+++ b/server/core/config.py
@@ -33,8 +33,11 @@ class Settings(BaseSettings):
secret_key: str = Field(env="SECRET_KEY", min_length=32)
cors_origins: List[str] = Field(env="CORS_ORIGINS")
- # Database Configuration
- database_url: str = Field(env="DATABASE_URL")
+ # Database Configuration. ``database_url`` is a computed property
+ # (see below) — the SQLite file name lives in ``WORKFLOW_DB_FILENAME``
+ # and resolves under ``DATA_DIR`` like every other state path,
+ # rather than being hardcoded inside a SQLAlchemy URL string.
+ workflow_db_filename: str = Field(env="WORKFLOW_DB_FILENAME")
database_echo: bool = Field(default=False, env="DATABASE_ECHO")
database_pool_size: int = Field(default=20, env="DATABASE_POOL_SIZE", ge=5, le=100)
database_max_overflow: int = Field(default=30, env="DATABASE_MAX_OVERFLOW", ge=10, le=100)
@@ -76,7 +79,8 @@ class Settings(BaseSettings):
# heartbeat interval — a worker drain completes within one polling
# cycle. Tune via env when SIGTERM-to-restart latency matters.
temporal_graceful_shutdown_seconds: int = Field(
- env="TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS", ge=1,
+ env="TEMPORAL_GRACEFUL_SHUTDOWN_SECONDS",
+ ge=1,
)
# Wave 12 canary-flag default flipped to True (2026-05-15).
# The Temporal-native event dispatch path
@@ -89,7 +93,8 @@ class Settings(BaseSettings):
# working unchanged for non-canary triggers. See
# docs-internal/event_framework.md § Rollback procedure.
event_framework_enabled: bool = Field(
- default=True, env="EVENT_FRAMEWORK_ENABLED",
+ default=True,
+ env="EVENT_FRAMEWORK_ENABLED",
)
# gRPC frontend port — the port ``temporal server start-dev``
@@ -97,14 +102,18 @@ class Settings(BaseSettings):
# ``.env.template`` (canonical default lives there). Reference:
# https://docs.temporal.io/references/configuration
temporal_frontend_grpc_port: int = Field(
- env="TEMPORAL_FRONTEND_GRPC_PORT", ge=1024, le=65535,
+ env="TEMPORAL_FRONTEND_GRPC_PORT",
+ ge=1024,
+ le=65535,
)
# Web UI port. ``temporal server start-dev`` defaults this to
# ``--port + 1000`` (i.e. 8233 alongside the default 7233 gRPC
# port); declared explicitly via ``--ui-port`` so the binding is
# intentional and surfaces in status snapshots.
temporal_ui_port: int = Field(
- env="TEMPORAL_UI_PORT", ge=1024, le=65535,
+ env="TEMPORAL_UI_PORT",
+ ge=1024,
+ le=65535,
)
# SQLite db path passed to ``temporal server start-dev
# --db-filename ...``. Resolved relative to ``DATA_DIR``
@@ -183,10 +192,14 @@ class Settings(BaseSettings):
# File-rotation knobs — only consulted when LOG_FILE is set.
# Default ceiling = 10 MiB × 5 backups = ~50 MiB on disk.
log_file_max_bytes: int = Field(
- default=10 * 1024 * 1024, env="LOG_FILE_MAX_BYTES", ge=1024,
+ default=10 * 1024 * 1024,
+ env="LOG_FILE_MAX_BYTES",
+ ge=1024,
)
log_file_backup_count: int = Field(
- default=5, env="LOG_FILE_BACKUP_COUNT", ge=0,
+ default=5,
+ env="LOG_FILE_BACKUP_COUNT",
+ ge=0,
)
# Rate Limiting
@@ -251,25 +264,20 @@ class Settings(BaseSettings):
def _expanduser_path(cls, v: Optional[str]) -> Optional[str]:
return str(Path(v).expanduser()) if v else v
- @field_validator("database_url", mode="after")
- @classmethod
- def validate_database_url(cls, v: str) -> str:
- """Expand ``~`` in sqlite paths + ensure parent dir exists.
-
- Parses the URL via SQLAlchemy's canonical parser instead of
- string surgery on ``:///``.
+ @property
+ def database_url(self) -> str:
+ """Compose the SQLAlchemy URL from ``DATA_DIR`` + ``WORKFLOW_DB_FILENAME``.
+
+ Always ``sqlite+aiosqlite:///<abspath>`` — the only DB engine
+ MachinaOS uses. Parent dir is mkdir'd here so the DB file can
+ be opened on first access without a separate bootstrap step.
+ Reads :meth:`_resolve_under_data` so the same DEV / daemon
+ toggle (``.env.dev`` swapping ``DATA_DIR=.machina``) that moves
+ every other state path moves ``workflow.db`` too.
"""
- if not v:
- return v
- from sqlalchemy.engine.url import make_url
- url = make_url(v)
- if url.drivername.startswith("sqlite") and url.database:
- db_path = Path(url.database).expanduser()
- db_path.parent.mkdir(parents=True, exist_ok=True)
- if str(db_path) != url.database:
- v = url.set(database=str(db_path)).render_as_string(hide_password=False)
- return v
-
+ db_path = Path(self._resolve_under_data(self.workflow_db_filename))
+ db_path.parent.mkdir(parents=True, exist_ok=True)
+ return f"sqlite+aiosqlite:///{db_path}"
@property
def is_development(self) -> bool:
@@ -282,11 +290,17 @@ class Settings(BaseSettings):
return not self.debug
def _resolve_under_data(self, path: str) -> str:
- """Resolve a path relative to data_dir, unless already absolute."""
- p = Path(path)
- if p.is_absolute():
- return str(p)
- return str(Path(self.data_dir) / p)
+ """Resolve ``path`` under ``data_dir``, returning an absolute path.
+
+ Thin delegate to :func:`core.paths._resolve_data_path` so the
+ single resolution algorithm lives in one place. Used by the
+ ``credentials_db_resolved`` / ``workspace_base_resolved``
+ properties and any plugin that needs a DATA_DIR-relative path
+ without importing ``core.paths`` directly.
+ """
+ from core.paths import _resolve_data_path
+
+ return str(_resolve_data_path(self.data_dir, path))
@property
def credentials_db_resolved(self) -> str:
@@ -310,4 +324,4 @@ class Settings(BaseSettings):
"extra": "ignore",
"env_parse_none_str": "none",
"env_nested_delimiter": "__",
- }
\ No newline at end of file
+ }
diff --git a/server/core/paths.py b/server/core/paths.py
index 2d5a831b..c417f9ff 100644
--- a/server/core/paths.py
+++ b/server/core/paths.py
@@ -93,18 +93,53 @@ def project_root() -> Path:
return _REPO_ROOT
-def machina_root() -> Path:
- """Absolute path of ``~/.machina/`` (or the configured DATA_DIR).
-
- ``Path.expanduser()`` is a no-op when there's no ``~`` to expand,
- so we can always call it unconditionally. After expansion: if
- absolute, use verbatim; if relative, resolve under repo root
- (back-compat with ``DATA_DIR=data`` etc.). Settings is
- instantiated lazily — Pydantic caches the result.
+def _resolve_data_path(base: str, subpath: str = "") -> Path:
+ """Canonical state-path resolution primitive. Always returns absolute.
+
+ Shared by :func:`data_path` (public entry point) and
+ ``Settings._resolve_under_data`` (the Pydantic-side mirror used by
+ state-path properties like ``credentials_db_resolved``). One
+ implementation so the two never drift.
+
+ Rules:
+ - ``Path.expanduser()`` on ``base`` — no-op when no ``~`` present.
+ - Absolute resolved ``base`` → used verbatim.
+ - Relative ``base`` → resolved under :func:`project_root` (so
+ dev mode's ``DATA_DIR=.machina`` lands at ``<repo>/.machina/``
+ regardless of the subprocess's cwd).
+ - Empty ``subpath`` → returns the resolved base.
+ - Absolute ``subpath`` → returned verbatim.
+ - Relative ``subpath`` → joined onto the resolved base.
+ """
+ b = Path(base).expanduser()
+ if not b.is_absolute():
+ b = project_root() / b
+ if not subpath:
+ return b.resolve()
+ p = Path(subpath)
+ return p.resolve() if p.is_absolute() else (b / p).resolve()
+
+
+def data_path(subpath: str | Path = "") -> Path:
+ """Absolute path of ``<DATA_DIR>/<subpath>``.
+
+ Single entry point for every state location MachinaOS reads or
+ writes. Reads ``Settings.data_dir`` (env var ``DATA_DIR``) — so
+ the dev / daemon split (``.env.dev`` vs ``.env.template``) moves
+ every state path together. Pass an empty ``subpath`` to get the
+ DATA_DIR root.
+
+ Settings is instantiated lazily — Pydantic caches the result.
+ Resolution rules: see :func:`_resolve_data_path`.
"""
from core.config import Settings
- p = Path(Settings().data_dir).expanduser()
- return p.resolve() if p.is_absolute() else (project_root() / p).resolve()
+
+ return _resolve_data_path(Settings().data_dir, str(subpath))
+
+
+def machina_root() -> Path:
+ """Absolute path of the configured DATA_DIR (= ``data_path()``)."""
+ return data_path()
def packages_dir() -> Path:
@@ -152,13 +187,13 @@ def package_dir(name: str) -> Path:
def claude_config_dir() -> Path:
"""``CLAUDE_CONFIG_DIR`` for spawned claude subprocesses.
- Resolves to ``<machina_root>/claude/``. Single source of truth for
+ Resolves to ``<DATA_DIR>/claude/``. Single source of truth for
the plugin's ``MACHINA_CLAUDE_DIR`` constant (re-exported from
``nodes/agent/claude_code_agent/_oauth.py`` for back-compat).
Stores OAuth tokens + session state — distinct from
:func:`claude_npm_dir`, which holds the downloaded CLI binary.
"""
- return machina_root() / "claude"
+ return data_path("claude")
def claude_npm_dir() -> Path:
@@ -173,8 +208,16 @@ def claude_npm_dir() -> Path:
def workspaces_dir() -> Path:
- """Root for per-workflow workspaces."""
- return machina_root() / "workspaces"
+ """Root for per-workflow workspaces.
+
+ Routes through ``data_path(Settings().workspace_base_dir)`` (env
+ var ``WORKSPACE_BASE_DIR``) so the path stays in lockstep with
+ every other state location — no hardcoded ``"workspaces"`` literal
+ that drifts when the env var changes.
+ """
+ from core.config import Settings
+
+ return data_path(Settings().workspace_base_dir)
def workspace_dir(workflow_id: str) -> Path:
@@ -204,18 +247,32 @@ def example_workflows_dir() -> Path:
def whatsapp_dir() -> Path:
- """Persistent WhatsApp session DB / state dir."""
- return machina_root() / "whatsapp"
+ """Persistent WhatsApp session DB / state dir.
+
+ Routes through ``data_path(Settings().whatsapp_data_subdir)``
+ (env var ``WHATSAPP_DATA_SUBDIR``) so the WhatsApp tree moves
+ with ``DATA_DIR``.
+ """
+ from core.config import Settings
+
+ return data_path(Settings().whatsapp_data_subdir)
def credentials_db_path() -> Path:
- """Encrypted credentials store (Fernet + PBKDF2)."""
- return machina_root() / "credentials.db"
+ """Encrypted credentials store (Fernet + PBKDF2).
+
+ Routes through ``data_path(Settings().credentials_db_path)`` (env
+ var ``CREDENTIALS_DB_PATH``) so the DB moves with ``DATA_DIR``.
+ """
+ from core.config import Settings
+
+ return data_path(Settings().credentials_db_path)
__all__ = [
"project_root",
"machina_root",
+ "data_path",
"packages_dir",
"package_dir",
"claude_config_dir",
diff --git a/server/nodes/whatsapp/_runtime.py b/server/nodes/whatsapp/_runtime.py
index bb7c96e6..12169963 100644
--- a/server/nodes/whatsapp/_runtime.py
+++ b/server/nodes/whatsapp/_runtime.py
@@ -36,6 +36,7 @@ class WhatsAppRuntime(BaseProcessSupervisor):
super().__init__()
if settings is None:
from core.config import Settings
+
settings = Settings()
self.settings = settings
@@ -43,11 +44,14 @@ class WhatsAppRuntime(BaseProcessSupervisor):
@property
def data_root(self) -> Path:
- sub = getattr(self.settings, "whatsapp_data_subdir", "whatsapp")
- base = Path(self.settings.data_dir)
- if not base.is_absolute():
- base = _PROJECT_ROOT / "server" / base
- return (base / sub).resolve()
+ # Routes through ``Settings._resolve_under_data`` so dev mode's
+ # ``DATA_DIR=.machina`` lands the WhatsApp tree at
+ # ``<repo>/.machina/whatsapp/`` (not ``<repo>/server/.machina/...``,
+ # which the old ad-hoc ``_PROJECT_ROOT / "server" / data_dir``
+ # logic produced when ``DATA_DIR`` was relative).
+ return Path(
+ self.settings._resolve_under_data(self.settings.whatsapp_data_subdir)
+ )
@property
def port(self) -> int:
@@ -107,7 +111,8 @@ class WhatsAppRuntime(BaseProcessSupervisor):
config["server"]["port"] = self.port
config["server"]["host"] = self.bind_host
(self.data_root / "configs" / "config.yaml").write_text(
- yaml.safe_dump(config, sort_keys=False), encoding="utf-8",
+ yaml.safe_dump(config, sort_keys=False),
+ encoding="utf-8",
)