When something does not work

My phone cannot connect

Check that the computer is awake and Lyre is open. Confirm you selected the correct host. Try both devices on the same trusted Wi-Fi and avoid guest isolation. Check whether your build needs a configured relay or private network. Create a fresh invitation if the previous one expired.

Do not disable device authentication or expose internal host ports to get past a connection error.

The preview is blank

First check whether the project opens in the desktop preview. If it does not, inspect the start command, missing dependencies and service errors. If desktop works but phone does not, inspect pairing, the selected app grant and client preview diagnostics.

A backend and frontend may need separate start commands. A native-only API will not become available merely because a page loaded.

My assistant is unavailable

Check provider diagnostics and complete that provider’s own installation or login. A Lyre account is not the fix for a coding provider login. Keep your draft while you repair the provider connection.

I cannot see my change

Check that the file saved successfully and that the preview belongs to the same project. Refresh if appropriate. Dependency, backend and native changes may require a restart; preserve unsaved work before restarting.

Lyre cannot finish starting

Keep the visible diagnostic code and check the startup screen’s logs before retrying. Note whether the app is waiting for the host, reporting a failed host start, or failing to connect. Save unsent work before restarting anything. Do not delete the application profile or pairing data to diagnose startup.

For a useful report, include the desktop/client versions, operating system and the first failing step. Review logs before sharing: remove credentials, pairing links, private paths and project content. See updates and reporting for version and release information.

Find the host setting that needs attention

Open Settings for the affected host and inspect its status and logs. A packaged desktop host and a separately started CLI host may use different profiles. Use the configuration location shown for that host; do not assume that changing another profile’s config.json will affect it.

Keep project startup scripts in the project’s configuration and provider options in the selected host’s settings. Save work before applying a host restart. Check one operation that uses the changed setting, and preserve the previous value for recovery. See configuration and credentials.

Use the CLI for the correct host

Use the CLI supplied with your compatible Lyre build. In the documentation, /path/to/host-cli means that executable’s actual path. Open its --help first; subcommands have their own --help. Do not install an unrelated upstream package merely because it has a similar command name.

The desktop CLI integration control manages command availability. If your shell cannot find the command after installation, reopen that shell and check the integration status. For a separately managed host, confirm the selected home/profile before operating it. onboard starts a host and can change configuration; it is not a read-only diagnostic command. See installation and device access.

An orchestration skill is missing or outdated

Open Settings for the host where your agents run, then Agents → Orchestration skills. Use that card to inspect the selected skills and their installation state, update them or uninstall a selected skill. Check that you are looking at the intended host before changing its installed instructions.

Skills provide instructions to an agent. Installing one does not authenticate a provider, run the workflow or grant device/project access. If the agent cannot use a skill, check the host’s installation result and the provider’s ability to load those instructions. Keep the upstream Paseo skill names used by the installed tools.

Foundation reference: Paseo documentation at Lyre’s pinned upstream revision. Lyre’s installed build and host permissions remain authoritative.

Worktree setup or teardown fails

A worktree is a separate checkout for a workspace. Review its selected base branch and the project’s worktree setup and teardown commands in Project settings. The host reads paseo.json from the committed base branch; an uncommitted edit in another checkout does not configure a newly created worktree.

A fresh worktree does not contain ignored dependencies or private environment files. Inspect the failing setup command and terminal output before approving dependency installation or copying private configuration. Teardown can run when the worktree is archived: preserve useful work and review that command before archiving. Do not remove a worktree directory manually as a troubleshooting shortcut. See project workflow.

Foundation reference: Paseo documentation at Lyre’s pinned upstream revision. Lyre’s installed build and host permissions remain authoritative.

A scheduled task did not run

In Schedules, check that the schedule is enabled, its selected repository and provider settings, its cron cadence and timezone, and its next run and recent run results. The host must remain running. A schedule creates a fresh agent for each run; a heartbeat targets an existing agent conversation.

Inspect a failed run’s error before retrying. Running once starts real agent work with the configured prompt and permissions; review those first, especially if the task changes files or calls a paid service. Pause a schedule while correcting repeated failures. See provider setup if the host cannot start its selected agent.

Foundation reference: Paseo documentation at Lyre’s pinned upstream revision. Lyre’s installed build and host permissions remain authoritative.

Titles, branch names or commit text are not generated

Metadata generation uses a separate short provider request, so a working chat does not by itself prove that metadata generation is configured. In Settings → Host → Metadata, check Automatic or Manual selection and whether the selected provider/model is available on that host. Manual selection tries the chosen model first; other configured candidates can still be used as fallbacks.

For project-specific wording, review the metadataGeneration instructions in the committed base branch’s paseo.json. Review generated commit and pull-request text before using it. Provider requests can send relevant task or diff context and use the provider’s account; never put credentials in those instructions. See provider diagnostics.

Foundation reference: Paseo documentation at Lyre’s pinned upstream revision. Lyre’s installed build and host permissions remain authoritative.

Pairing, direct connections and revoked access

Direct Connection requires the six-digit owner code from the host’s Pair Device settings, including when a nearby computer was discovered automatically. Discovery fills connection details; it does not grant access. Use a fresh host-issued code if a code expired or was already used. If rate limited, wait before trying again rather than repeatedly submitting codes.

Reconnect uses the saved device credential. After revocation, obtain a new approved invitation; do not bypass authentication. Older remote direct profiles may need to pair again after the host update. Manual address entry remains available when nearby discovery is unavailable.

Plain HTTP/WS direct traffic is not encrypted by the pairing-code exchange. Use the supported HTTPS/WSS mode for transport encryption. A same-network connection does not establish off-network relay availability. The CLI’s daemon pair --full-host --device-name NAME approves owner access to all projects, agents, files, terminals and host settings; use it only for an intended owner device. An app-viewer invitation has a narrower scope. See access roles and connectivity.

A plugin is incompatible with the app or host

Keep the diagnostic’s required range and actual app/daemon version. Plugin compatibility uses the foundation version reported by those runtimes, not the Lyre display version. If the runtime version is unknown, resolve that version problem before loading the plugin. Use a compatible plugin release or a compatible app/host build.

A missing requirements.paseo targets the pre-0.8 foundation and is rejected on 0.8 and later. Ask the author to complete the runtime-entry migration and declare the versions they support. Invalid ranges must be valid npm semver ranges; adding "*" or a wider range alone does not migrate code. Authors should verify both client and host before declaring compatibility. See runtime-entry migration and plugin trust.

Foundation reference: Paseo documentation at Lyre’s pinned upstream revision. Lyre’s installed build and host permissions remain authoritative.

An older plugin entry point cannot load

Ask the plugin author for a migrated release. Supported root entry filenames are index.client.ts or index.client.tsx, and/or index.server.ts or index.server.tsx. At least one is required. A legacy index.ts or index.tsx alone is rejected before plugin execution.

Authors must separate UI code into client/, host operations into server/, and shared contracts into shared/; move registrations and update SDK imports as part of migration. Renaming a file or changing only the version range is insufficient. Keep Node APIs and credentials out of client imports. Validate the migrated plugin on an isolated development host before offering it to users. See creating a plugin for the Lyre workflow.

Foundation reference: Paseo documentation at Lyre’s pinned upstream revision. Lyre’s installed build and host permissions remain authoritative.

Share a useful report

Include the Lyre version, computer and phone platforms, the action you attempted, and the visible diagnostic code. Explain what you expected and what happened. Remove keys, source, addresses and personal data from screenshots or logs before sharing them.

Join the Lyre community to discuss the issue.