pithyx dev

pithyx dev runs a mock desktop on your machine: your built frontend in the same sandbox as on the box, the SDK’s host side, and a proxy to the backend that behaves like the box’s. The backend runs with docker compose. There is no development mode on the box; with Vite use the plugin @pithyx/cli/vite and run vite instead (@pithyx/cli).

Synopsis

pithyx dev [project folder] [--frontend <folder>] [--port <port>] [--host <host>] [--endpoint <n=url>]... [--no-docker]

Options

Option	Value	Type	Default	Description
--frontend	<folder>	string	dist	The built frontend
--port	<port>	string	7400	The port
--host	<host>	string	127.0.0.1	The address to listen on
--endpoint	<n=url>	string, repeatable	–	Reach the endpoint n at url instead of through Docker, for example –endpoint api=http://localhost:8080 (repeatable)
--no-docker	–	boolean	off	Do not start the backend; endpoints without –endpoint answer 503

--port must be an integer from 1 to 65535. An IPv6 --host is printed in brackets. --endpoint names an endpoint the manifest declares and a URL, for example api=http://localhost:8080; an undeclared name fails.

What runs

• The page is served at http://<host>:<port>/, the frontend as /apps/<id>/ with the box’s headers. Files are read on each request: rebuild and reload to see a change.
• The backend starts when the manifest has one, some endpoint has no --endpoint, and --no-docker is not given: docker compose --project-name pithyx-dev-<id with _ for dots> --file <compose> --file <override> up --detach --wait --build. <compose> is backend/compose.dev.yaml when it exists, else the file of backend.compose. The override publishes each endpoint’s port on 127.0.0.1 at a port Docker picks; the proxy reaches it there.
• With --no-docker, endpoints without --endpoint answer 503.
• Ctrl+C or SIGTERM stops the server, runs docker compose down (volumes stay) and exits with 0.

Files

File	Access
pithyx.json	read; it must exist and be valid
icon.svg, the frontend folder	read on each request
backend/compose.dev.yaml or the file of backend.compose	read by docker compose
a temporary folder pithyx-dev-* with compose.ports.yaml	written at start, removed after down

Exit codes

Code	When
0	Stopped with Ctrl+C or SIGTERM.
1	pithyx.json is missing or not valid, --endpoint is malformed or names an undeclared endpoint, Docker fails, or the port cannot be opened.
2	--port is not a port, or more than one project folder.

Findings

dev prints no findings. Run pithyx validate to see why a manifest is not valid.

Examples

pithyx dev                                         # http://127.0.0.1:7400/
pithyx dev --port 8000 --host 0.0.0.0              # reachable from other machines
pithyx dev --endpoint api=http://localhost:8080    # your own server for the endpoint api
pithyx dev --no-docker                             # frontend only