Configuration

What is in dwell.json?

.dwell/dwell.json lives in the project directory. Dwell reads and validates this file when resolving the project. Prefer CLI commands: they validate the entire configuration and synchronize related local state.

• project is the display name, slug the technical name for runtime resources and hostBase the base for local hosts without .localhost or .local.
• stack describes backend, frontend and their workspace directories; runtime contains the PHP version when a backend is active.
• services controls optional development services. routing defines hosts and URL paths independently of workspace directories.
• network controls LAN sharing, tool sharing and interface selection. identity remains the project and data identity generated by Dwell.

Inspect configuration

Run commands in the project directory. config show displays project name, slug, host base, primary route and network settings. It is a summary, not a complete JSON dump.

dwell config show

Change project values

dwell config opens the interactive terminal editor. For a targeted change or a script, use config set with the appropriate flags.

dwell config

dwell config set --host demo

--host demo sets the host base without a domain suffix. Host, slug or network changes can restart active services. Check the printed URLs afterwards; the display name is independent of the folder name.

Choose the right command

Not every setting belongs to config. Choose the command for the kind of change you need.

config / config set

General project and network settings such as display name, slug, host base or LAN sharing.

stack set

Change roles, stack profiles and the PHP runtime. The project must be stopped; type and framework version changes are blocked for populated role directories.

paths move

Move a backend or frontend directory and update configuration accordingly. This does not change a URL.

routing

Inspect or change application hosts and URL paths. Workspace directories are independent of these.

services enable / disable

Enable or disable optional development services.

These examples are independent actions, not a single command sequence. Stop with dwell down before stack set or paths move. PHP 8.4 must fit the backend profile; moving requires an active backend and an empty or nonexistent api directory.

dwell stack set --php 8.4

dwell paths move backend api

dwell routing list

A small configuration excerpt

This excerpt shows only roles and PHP for Symfony 7.4 with React 19.3. Other required fields are deliberately omitted. Do not replace your file with this excerpt.

{
  "stack": {
    "backend": { "type": "symfony", "version": "7.4", "dir": "backend" },
    "frontend": { "type": "react", "version": "19.3", "dir": "frontend" }
  },
  "runtime": { "php": { "version": "8.4" } }
}

Notes & limits

Keep the identity generated by Dwell. Secrets are stored separately and do not belong in dwell.json. Generated runtime files are not configuration sources. A role directory is a workspace path; production output and deployment are not configured here. After moving the entire project folder, dwell reinit is the appropriate step.

Next steps

Before stack or PHP changes, check compatibility in the stacks guide. The projects guide covers starts and stops; the technical reference contains exact schema and mutation rules.

Technical reference