Connect an existing app

1 · Open the project you already use

Your editor, repository, framework and hosting setup all stay as they are. Lyre runs a local copy on your computer and opens the app in the browser inside Lyre, or on an authorized client. You do not need a coding assistant to preview an app.

1. Install Lyre

   Get it from the download page. Use the computer that will stay switched on while you work: your project runs there.

2. Open the project in Lyre

   Choose the project’s folder in Lyre and open a workspace. For your first test, use the checkout you already have. Do not start from a fresh copy yet.

3. Pick the right folder

   If your repository has a frontend/ and a backend/ folder, choose the folder that contains both. Lyre runs every command from that workspace directory.

4. Keep your usual tools

   Follow your project’s own README and lockfile, and use the package manager it already uses. Then find the recipe for your stack below.

2 · Prepare the host once

Do this on the computer that runs Lyre, before Lyre starts anything. You only do it once per checkout.

1. Install the runtimes your project needs

   Node.js, Python, Flutter, Docker, whatever your project uses. Then open a plain terminal on this computer and check that the normal start command works there.

2. Install the project’s own dependencies

   Follow its README. For an npm project with a valid lockfile that is usually npm ci. If the project uses pnpm, Yarn or another manager, keep that manager.

3. Create the local environment

   Set up your app’s local environment files, test database and any migrations it needs. Keep backend credentials on the host, out of frontend bundles and out of Git.

4. Stop your temporary servers

   If you started servers by hand to check the project, stop them now. Lyre is about to start the same ports.

3 · Save how the app starts

A service is a long-running command Lyre supervises and gives a port to. You tell Lyre about your app once, and Lyre starts it from then on.

Example: a frontend and a 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 folders and commands to match your app. Merge this into lyre.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 read its port

   The backend has to listen on the port Lyre assigned it (8000 in this example). For an existing Express app the 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 as they are.

2. Send browser requests through the frontend

   Your frontend’s server has to forward API calls to the backend. That is the next section.

3. Start it

   Save, return to the workspace and start preview. Lyre starts backend first, then preview, and both keep running together.

4 · Make API requests work on the phone

In a browser, localhost means the device showing the page. A phone cannot use a frontend’s hard-coded http://localhost:8000 to reach your computer’s backend. Instead, ask for a relative path and let the frontend server forward it.

fetch('/api/items')

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

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

This keeps /api as the browser path, so your backend must serve /api/items. If it serves /items instead, add a reviewed path rewrite in the proxy. If your app uses WebSockets, add a proxy rule for its real socket path. Keep authentication and origin checks appropriate to your app. Vite proxy reference →

5 · Start once and check the result

1. Start the app

   Use the app/service start control in the workspace for preview, or open the prepared app tile from Apps.

2. Watch what Lyre starts

   Lyre reuses services already running in that workspace. Otherwise it starts one companion named backend, api or server, in that order, before the frontend you chose.

3. Wait for both ports

   Lyre opens the preview once the startup check passes, or shows a recoverable error after about 60 seconds.

4. Do something real

   Load a page, then run an action that calls the API and check the result in the app. If it fails, read both services’ output.

6 · Open it on a paired device

1. Keep the computer ready

   Leave the computer awake with Lyre open and the workspace available. Start with both devices on the same trusted network.

2. Pair the device

   Follow device pairing and approve the access you intend on the host. A developer device needs access to this project. See Pair device.

3. Open the app on the phone

   Open the prepared app from Apps, or use the workspace’s Open app control. The same frontend and backend startup applies.

4. Test it properly

   Try navigation, typing and one API-backed action. Save an edit on the computer and check whether your framework refreshes it; use Refresh or restart when it needs one.

5. Share it with someone who only needs the app

   Send an app-scoped invitation from the host’s sharing controls. They open the app you shared and need no source or terminal access. Prepare and start the shared app on the host first.

If a page loads but the app does not work

No app tile appears

Save a service named preview, frontend, web or dev. Several differently named services are ambiguous. Open the workspace and configure its frontend.

Only the frontend starts

Check that the companion is named backend, api or server and has Run as a service turned on. A package.json script on its own is not a Lyre service.

Port conflict, or a startup timeout

Compare the port that is really listening with the one in lyre.json. Use distinct ports, stop only the old test instance you started, and read the service output for a missing runtime or dependency.

It works on the computer; API calls fail on the phone

Remove browser calls to host-only localhost URLs. Use the frontend proxy, then check the real API response and how login and cookies behave.

403, blocked host or blocked origin

Allow only the exact preview hostname or origin your app needs in its development settings. Keep authentication; do not allow every host or origin.

Changes do not appear

Check you are on the checkout you think. Refresh for static output, rebuild generated output, and restart after changing environment variables, dependencies or server configuration.

Keep the visible diagnostic code, and open the affected service’s terminal or output before retrying. Troubleshooting covers host and worktree problems.

Keep a short feedback loop

1. Make one change

   Do it yourself or ask your assistant for one thing at a time.

2. Review and save the changed files

   Read the diff before you keep going.

3. Test the interaction you changed

   Try it on the computer and on the phone. Test empty input, valid input and an error.

4. Commit a working version

   So you can compare against it later and recover if the next change goes wrong.

Keep your existing workflow

Your editor, package manager, Git history, CI and production deployment all remain yours. Lyre only runs the commands you configure, against the workspace you selected.

Start with development data, keep your existing deployment configuration, and commit the shared project configuration once it is ready for teammates or new worktrees.