Mechasmmechasm logoMechasmbeta
Back to Docs

CLI Local Apps & Devices

Register a local app, approve its ports, and choose a device for local test runs.

Use the CLI service when a test needs an app running on your computer. The service stays connected and ready between runs. During an authorized run, Mechasm connects to the selected app; that connection closes when the run work ends.

The CLI downloads its pinned FRP tunnel binary the first time a local tunnel is needed. No separate mechasm-local helper install is required.

Start the service and register an app

mechasm service start
mechasm service status
mechasm local register --project PROJECT_ID --url http://localhost:3000 --ports 3000,8080

Replace the project ID and ports with the ones your app uses. Registration requires the service to be online. It approves this device for the project, selects it, and sets the project’s URL and full port list. Include the URL’s port. Each project can approve up to 16 ports. local ports set replaces the list; it does not append ports.

For example, approve 3000 for a frontend and 8080 for an API if your app uses those ports. Do not include a port unless the test needs to reach it.

Choose a device

mechasm local list --project PROJECT_ID
mechasm local select --project PROJECT_ID DEVICE_ID

For a local app address such as http://localhost:3000, an eligible device must be online, approved for the project, and approved for the current ports. With Automatic, a new run uses the only eligible online device. If more than one device is eligible, choose one in project settings or with local select.

An explicitly selected offline, revoked, or unapproved device fails with an actionable error. The run does not switch to another device. The project URL and port list are shared across its devices; selecting another device does not restore different URL or port settings. Existing runs keep the device and port settings they started with.

For a loopback project address such as http://localhost:3000, a selected device lets the test reach the app on that device. If no device is registered to the project, the saved address is used directly from the test environment. Non-loopback project addresses are always used directly, even when a device is selected.

Without a device connected to the project, a local app address can still be used when running tests from a machine that can reach it. Non-local app addresses are used directly.

Stop or unregister

mechasm local unregister --project PROJECT_ID
mechasm service stop

local unregister removes this device’s access to the project and clears it as the selected device, but keeps the CLI signed in and ready for other projects. service stop stops the service and closes connections for active runs, but leaves project access in place. You can rename or revoke a device under Profile → My devices.

Share local app state safely

Runs that use the same local app share its application state and data. Use separate test data if concurrent runs could interfere. Multiple projects can use the same port on one device, but they will reach the same app on that computer.