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.

If Lyre opens but the issue remains, use Error history to find the affected work, inspect its saved occurrences and copy redacted details.

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 lyre-foundation, the CLI supplied with your Lyre desktop build. Start with lyre-foundation --help; subcommands have their own --help. See the standard desktop CLI paths and full-path commands if it is missing from PATH, or the CLI quickstart for a standalone npm installation.

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 AI & agents → Agent software. 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. Use the skill names and aliases shown by the installed tools.

See agent skills and instructions for the current setup.

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 lyre.json (or the supported legacy 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.

See workspaces and project setup.

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.

See Schedules for task setup, timing and run history.

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 lyre.json (or the supported legacy 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.

See settings scope and reviewing Git changes.

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.

See plugin compatibility and installation and static plugin checks.

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.

See client, host and shared plugin entries.

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.