Connect an existing app

1. Open the project you already use

Your existing editor, repository, framework and hosting setup can stay in place. Lyre runs a local copy on your computer and opens its browser interface in Studio or on an authorized client. You do not need a coding assistant to preview an app.

1. Install a compatible Lyre desktop/client build from available downloads.
2. Clone or open your existing project on the host computer. Choose its folder in Lyre and open a workspace. For your first test, use the existing local checkout.
3. For a repository with frontend/ and backend/, choose their common project root. Commands run from the workspace directory.
4. Keep using your project’s README, lockfile and existing package manager. Use the recipe for your stack below.

A preview requires a browser interface. Expo, Capacitor and Flutter web targets can provide one; native-only screens, desktop windows and Unity projects need a separate supported workflow.

2. Prepare the host once

1. Install the runtimes required by your project, such as Node.js, Python, Flutter or Docker. Confirm the normal start command works in a fresh terminal on this computer.
2. Install the project’s locked dependencies and prepare its development environment using its README. For npm projects with a valid lockfile, that is commonly npm ci; keep pnpm, Yarn or another manager where the project uses it.
3. Set up your application’s local environment files, test database and required migrations. Keep backend credentials on the host, out of frontend bundles and Git.
4. Stop the temporary servers you started for this manual check before asking Lyre to start the same ports.

Saving a start command does not install dependencies, create a database or copy private environment files. A new Git worktree needs its own preparation because ignored files and installed packages are not automatically copied.

3. Save the app’s start commands

1. Open Project settings → Scripts for the selected project.
2. If the App start scripts section appears, select its preview port and choose Detect preview. Review the proposed command and port, choose Add to draft, then Save. Detection proposes a standard web command; it does not discover your entire backend.
3. For manual setup, add a script named preview for the frontend. Enter its command, turn on Run as service, save the script and save Project settings.
4. If the app has a separate HTTP backend, add a service named backend for it. Use distinct ports and the two-service example below.

New services created in the script editor use assigned ports. Your command must read PASEO_PORT, or set a matching fixed port in the project’s paseo.json. The recipes use explicit ports for an easy first setup. Edit or merge the relevant scripts entries; preserve existing settings, scripts and worktree commands.

If a paseo.json already exists, review that configuration instead of replacing it with an automatic proposal. Reload Project settings after editing the file externally.

Example: frontend and backend together

This example assumes a Vite frontend in frontend/, a Node HTTP backend in backend/, and a dev script in each package. Change the directories and commands to match your app. Merge this into paseo.json at their common root:

{
  "scripts": {
    "preview": {
      "type": "service",
      "command": "npm --prefix frontend run dev -- --host 127.0.0.1 --port 5173 --strictPort",
      "port": 5173
    },
    "backend": {
      "type": "service",
      "command": "npm --prefix backend run dev",
      "port": 8000
    }
  }
}

1. Make the backend listen on Lyre’s assigned PASEO_PORT (8000 here). For an existing Express app, its listen call can use app.listen(Number(process.env.PASEO_PORT || 8000), "127.0.0.1"). Keep the rest of your backend initialization and routes.
2. Connect browser requests to the backend through the frontend’s server-side proxy, as shown next.
3. Save, return to the workspace and start preview. Lyre starts backend first, then preview; both keep running concurrently.

Use separate service entries for the two long-running processes. npm run backend && npm run frontend waits for the backend to exit, so it does not start both together.

4. Make API requests work on the phone

In the browser, localhost refers to the device displaying the page. A phone cannot use a frontend’s hard-coded http://localhost:8000 as the host computer’s backend address. Have the browser request a relative path, such as fetch('/api/items'), and let the frontend server forward it to the backend on the computer.

For the example above, merge this server.proxy entry into your existing vite.config.ts or vite.config.js; preserve your plugins and other options:

server: {
  proxy: {
    '/api': {
      target: 'http://127.0.0.1:' + (process.env.PASEO_SERVICE_BACKEND_PORT || '8000'),
      changeOrigin: true
    }
  }
}

This preserves /api: the backend must serve /api/items. If it instead serves /items, add a reviewed path rewrite in your proxy. Add a WebSocket proxy rule for your app’s actual socket path if it uses one. Keep authentication and origin checks appropriate to your app. See the Vite proxy reference.

For other frameworks, use their equivalent server-side proxy or API routes. Lyre’s PASEO_SERVICE_BACKEND_PORT is available to the host process; it is not automatically injected into browser JavaScript. Host-only service URLs are not phone URLs. If you keep an existing hosted API, retain its HTTPS endpoint and configure that API’s authentication and allowed origins for your preview.

5. Start once and check the result

1. Use the workspace’s app/service start control for preview, or open the prepared app tile from Apps.
2. Lyre reuses services already running in that workspace. Otherwise it starts one companion named backend, api or server, in that priority order, before the selected frontend.
3. Wait for both ports to become reachable. Lyre opens the preview after the startup check, or shows a recoverable error after about 60 seconds.
4. Load a page, perform an action that calls the API, and verify the result in the app. Check both services’ output if it fails.

The startup check confirms listening services; it does not prove your database, sign-in or every API route works. Lyre does not wait for the backend to finish all application-specific initialization before launching the frontend. Handle database readiness in your backend or your existing startup tool.

Only one named companion is started automatically. For three or more processes, see Docker and larger stacks. Closing a preview or ending an agent conversation does not stop its services. Use each service’s Stop control when you want to shut down the app.

6. Open it on a paired device

1. Keep the computer awake, Lyre open and the workspace available. Start with both devices on the same trusted network.
2. Follow device pairing and approve the intended access on the host. A developer device needs access to this project.
3. On the phone, open the prepared app from Apps, or use the workspace’s Open app control. The same frontend/backend startup applies.
4. Try navigation, typing and an API-backed action. Save an edit on the computer and check whether your framework refreshes it; use Refresh or restart when required.
5. For someone who only needs to use the app, send an app-scoped invitation through the host’s sharing controls. They open the received app; they do not need source or terminal access. Prepare and start the shared app on the host first.

Pairing is not public hosting or an App Store release. Local-network previews are free; off-network app previews require the supported remote connection and Lyre Pro. See remote testing.

If a page loads but the app does not work

Keep the visible diagnostic code. Open the affected service’s terminal/output before retrying. See troubleshooting for host and worktree problems.

Keep a short feedback loop

1. Make one change yourself or with your assistant.
2. Review and save the changed files.
3. Test the affected interaction on the computer and phone.
4. Commit a working version so you can compare and recover changes.

Test empty input, valid input and an error. A working screenshot is only the beginning of testing an app.

Keep your existing workflow

Your editor, package manager, Git history, CI and production deployment remain yours. Lyre runs the commands you configure against the selected local workspace. Start with development data, preserve your existing deployment configuration, and commit the shared project configuration when it is ready for teammates or new worktrees.