Routing & access

What is a route?

Use routing when inspecting or changing an application’s local address. It is independent of whether your code lives in app, backend or frontend. Entries are stored under routing.entries in .dwell/dwell.json.

• id names the entry, such as backend or frontend. Use this ID when changing the route.
• target selects an active role: backend or frontend.
• host is the hostname without a protocol or port, such as my-project.localhost.
• path is the URL path, such as / or /api. A project directory name is not a URL setting.

Root, /api or subdomain

These examples use the host base my-project. .localhost is for local development on your machine. init creates different default routes depending on the selected roles.

Backend only or frontend only

The active role uses the root: http://my-project.localhost/.

Symfony, Laravel or Custom PHP with a frontend

The frontend uses http://my-project.localhost/; the backend defaults to http://my-project.localhost/api.

CMS with a frontend

WordPress, TYPO3 and Shopware 6 receive their own root URL, such as http://cms.my-project.localhost/. The frontend remains at http://my-project.localhost/.

API subdomain as an alternative

A backend can instead use http://api.my-project.localhost/. Select the offered backend URL during interactive init or change the route later. This address is not automatically created in addition to the /api route.

For a backend prefix, Dwell removes /api before passing the request to the application. The application must still handle generated URLs and assets to match its external address. Applications with multiple direct PHP entrypoints need a root URL; direct PHP script requests are blocked at a backend prefix.

Inspect routes and addresses

Run these commands in the project directory. routing list shows entries with ID, target, host and path. A star marks the primary route.

dwell routing list

Routing defines the intended mapping; dwell access shows the resulting configured URLs, including the current gateway port. It is not a reachability check. Start with dwell up and inspect runtime status with dwell ps when needed.

dwell access

dwell open opens the primary URL in your browser. A frontend route at the root takes priority; otherwise the first configured route is used. open also does not check whether the application is running.

dwell open

Change a backend URL

Suppose your project has an active backend role and a route named backend. Check its ID with routing list first. Move it to an API subdomain at the root as follows:

dwell routing update backend --host api.my-project.localhost --path /
dwell up
dwell access

Dwell updates project configuration and synchronizes runtime and gateway state. up then ensures the project is running with the new configuration. Check the resulting address with access. Adjust application URL settings if needed.

The local gateway

The shared local gateway receives requests for your projects and forwards them to the matching role. Even frontend-only projects therefore need Docker.

Dwell prefers local HTTP port 80 and can fall back to a higher port, such as http://my-project.localhost:18080/. On Windows, the selected high port is used directly. Use the printed address instead of guessing a port.

Local HTTPS is optional. When enabled, the local gateway redirects HTTP to its HTTPS port; normal project links and access still report HTTP addresses. Prerequisites and certificate details are in the runtime reference.

Notes & limits

Every active role needs a route. Dwell checks duplicate IDs, conflicting host/path pairs and hosts already owned by other projects. tools.[hostBase].localhost is reserved when Mailpit or phpMyAdmin is active. For custom domains outside the managed .localhost names, you must arrange name resolution yourself.

Next steps

Use the services guide for the database, Mailpit and phpMyAdmin. General host and project settings are covered by Configuration.

Technical reference