Mohamed BoudraandGitHub
dfd18a44a7
* feat(website): nest docs pages under landable groups The docs sidebar could already render groups from subdirectories in public-docs, but nothing used it because every doc was a flat file, and two things stopped it being usable. A group had no page of its own, so its label was only a toggle and its name came from the directory name via formatLabel. A directory's index.md now supplies the group's label, order, and href, which makes the group landable and lets the label be authored rather than derived. Categories and top-level directories named the same thing, so a categorised doc at hub/index.md produced a group nested inside its own category. Only directories below the top level become groups now. Also fixes two behaviours in the sidebar: - The open/closed effect assigned containsActive on every change, so a group you expanded to browse collapsed the moment you navigated anywhere else. Navigating in now opens a group and navigating away leaves it alone. - The sidebar scrolls independently of the page and never scrolled the active entry into view, so loading or refreshing a page far down the list left the sidebar parked at the top with no visible position. The group row is a single target: it navigates and expands, and collapses when clicked again from the page it points at. A separate chevron button would put two actions a few pixels apart. * docs(hub): document Hub Adds a Hub section covering what it is, how it works, daemons, triggers, configuration, activity, and the two ways to run it. The section separates using Hub from running it. Overview, quickstart, daemons, triggers, and configuration hold regardless of who operates the deployment; the self-hosting branch owns deploying the service and creating the GitHub, Slack, and Discord apps it talks to. That split falls on a real seam, because those apps are exactly what a hosted Hub would own on your behalf. Hosted is a placeholder until it ships. Each provider gets a trigger page carrying its events, filter semantics, and the full paseo.event.* reference for the data a prompt can read. That data is the thing a config author actually needs and the thing they cannot get from anywhere else. Every YAML block was parsed against the Hub config schema rather than eyeballed, which kept several plausible-looking things out of the docs: worktree prNumber takes a literal number and not a merge variable, only daemon environments run today, and github.push has no actor so it can never satisfy the required from_users filter. Troubleshooting moves to order 90 so it stays last. * refactor(website): let the active docs entry scroll itself into view The layout queried the sidebar for the active entry after every navigation, which coupled it to when that entry mounts. A link inside a collapsed group only mounts once the group's own effect opens it, so the query could run against a DOM that does not contain it yet. Moving the scroll to the entry removes the ordering question rather than answering it, and drops the ref and the cross-component query. Reported by Greptile on #2864. The failure it described does not reproduce: navigating from a page outside a collapsed group into one of its children still scrolls correctly, verified with the group confirmed collapsed and the sidebar forced to the top. The coupling was real even though the bug was not. * docs(hub): stop listing BETTER_AUTH_URL as required It falls back to PASEO_CLOUD_PUBLIC_URL, so a deployment that sets the public origin already has a correct auth base URL. Listing it as required made the Fly recipe look incomplete when it was not. Moved to optional with its default, and recorded what actually breaks without BETTER_AUTH_SECRET: the auth routes close and nobody can sign in. Reported by Codex on #2864, which read the same inconsistency the other way round and proposed adding the variable to the Fly example. * docs(hub): attach a database in the Fly recipe The Fly section showed inline config and a secrets command, neither of which supplied DATABASE_URL. It defaults to localhost:5432, which on Fly reaches nothing, so the documented deployment could not start. fly postgres attach sets DATABASE_URL as a secret, so the step is the attach itself rather than another variable to copy. Reported by Codex on #2864. * docs: align Hub self-hosting contract
92 lines
5.0 KiB
Markdown
92 lines
5.0 KiB
Markdown
---
|
|
title: Troubleshooting
|
|
description: Why Paseo can't find a provider you've installed, and how to fix the PATH and environment mismatches behind most setup issues.
|
|
nav: Common problems
|
|
order: 90
|
|
category: Troubleshooting
|
|
---
|
|
|
|
# Troubleshooting
|
|
|
|
Almost every "it works in my terminal but not in Paseo" problem is the same thing: Paseo and your terminal aren't searching the same `PATH`. This page covers how to spot that and fix it.
|
|
|
|
## Paseo can't find my provider
|
|
|
|
A provider you've installed shows as **Not installed**.
|
|
|
|
Paseo launches the agent CLIs you've already installed, it doesn't bundle them (see [Providers](/docs/providers)). So it has to find the command on its own `PATH`. If your shell only adds that location to `PATH` under certain conditions, Paseo can miss it.
|
|
|
|
### See what Paseo sees
|
|
|
|
Open **Settings → your host → Providers**, tap the provider, then tap **Diagnostic**. The rows that matter:
|
|
|
|
- **Resolved path** — where Paseo found the binary, or `not found`.
|
|
- **Daemon PATH** — the `PATH` Paseo is searching. Compare it to `echo $PATH` in a fresh terminal.
|
|
- **Version** — whether the binary actually runs.
|
|
|
|
`not found` together with a **Daemon PATH** that's missing your binary's directory is the common case: that directory is on your terminal's `PATH` but not on Paseo's.
|
|
|
|
### Fix it
|
|
|
|
The durable fix is to make sure the command is on `PATH` for a normal login shell, then restart Paseo, see [why Paseo's environment can differ](#why-paseos-environment-can-differ-from-your-terminal) for why that's the test that matters.
|
|
|
|
If you'd rather pin it directly, set the binary path in `~/.paseo/config.json`:
|
|
|
|
```json
|
|
{
|
|
"agents": {
|
|
"providers": {
|
|
"claude": {
|
|
"command": ["/absolute/path/to/claude"]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
`command` is `[binary, ...args]` and fully replaces the default launch command for that provider. Find the real path with `which -a claude`. `type -a claude` also tells you if `claude` is only a shell alias or function, those won't work, Paseo runs the binary directly, so use the path it points to. Restart the daemon after editing (see [below](#i-changed-configjson-but-nothing-happened)).
|
|
|
|
For alternative endpoints, multiple profiles, custom binaries, and ACP agents, see [Custom providers](/docs/custom-providers). For per-agent install links, see [Supported providers](/docs/supported-providers).
|
|
|
|
## Why Paseo's environment can differ from your terminal
|
|
|
|
The same mismatch shows up anywhere Paseo runs your tools, an agent, or a terminal, reporting `command not found` for something you use every day.
|
|
|
|
When you open the **desktop app** from the Dock or Finder, the OS hands it a stripped-down environment, not your terminal's `PATH`. To compensate, Paseo runs your login shell once at startup (`$SHELL -i -l -c`), captures its environment, and hands that to the daemon and everything it spawns. The rule of thumb: **if a brand-new terminal can run the command, Paseo should too.** That's also the test, open a fresh terminal and try it there.
|
|
|
|
When you start the daemon yourself from a terminal (`paseo`), there's no login-shell step, it simply inherits that terminal's environment.
|
|
|
|
Either way, the fix for a missing tool lives in your shell config (`.zshrc`, `.zprofile`, …), not in Paseo. Tools installed through version managers (asdf, mise, nvm, …) are the usual offenders, make sure they initialize for a clean login shell, not only inside one you've already opened.
|
|
|
|
This login-shell step runs on macOS and Linux. On Windows, Paseo uses the environment it was launched with.
|
|
|
|
## Reading the logs
|
|
|
|
- **Desktop app** — the login-shell resolution is logged here. Look for `[login-shell-env]`: `applied` means it worked (it logs the `PATH` before and after); `failed; keeping inherited env` means it fell back to the stripped-down environment, with a `reason` (a timeout, a non-zero exit from your shell config, no output, …). A slow or erroring `.zshrc`/`.zprofile` is the usual cause.
|
|
- **Daemon** — `~/.paseo/daemon.log` (`$PASEO_HOME/daemon.log` if you've set a custom home).
|
|
|
|
Desktop app log location:
|
|
|
|
| Platform | Path |
|
|
| -------- | ------------------------------- |
|
|
| macOS | `~/Library/Logs/Paseo/main.log` |
|
|
| Linux | `~/.config/Paseo/logs/main.log` |
|
|
| Windows | `%APPDATA%\Paseo\logs\main.log` |
|
|
|
|
## I changed config.json but nothing happened
|
|
|
|
`config.json` is read when the daemon starts. Restart it after editing:
|
|
|
|
```bash
|
|
paseo daemon restart
|
|
```
|
|
|
|
Or in the app, open **Settings → your host → Overview** and use **Restart daemon**. Running agents keep going, and clients reconnect automatically.
|
|
|
|
## Still stuck?
|
|
|
|
- [Custom providers](/docs/custom-providers) — endpoints, profiles, binaries, ACP agents.
|
|
- [Configuration](/docs/configuration) — `config.json`, environment variables, logging.
|
|
- [How Paseo resolves your login shell](https://github.com/getpaseo/paseo/blob/main/packages/desktop/src/login-shell-env.ts) — the exact code that loads your shell environment.
|
|
- [Report an issue](https://github.com/getpaseo/paseo/issues).
|