alp
View as markdown

Troubleshooting

Almost every "it works in my terminal but not in alp" problem is the same thing: alp and your terminal aren't searching the same PATH. This page covers how to spot that and fix it.

alp can't find my provider

A provider you've installed shows as Not installed.

alp launches the agent CLIs you've already installed, it doesn't bundle them (see Providers). So it has to find the command on its own PATH. If your shell only adds that location to PATH under certain conditions, alp can miss it.

See what alp sees

Open Settings → your host → Providers, tap the provider, then tap Diagnostic. The rows that matter:

  • Resolved path — where alp found the binary, or not found.
  • Daemon PATH — the PATH alp is searching. Compare it to echo $PATH in a fresh terminal.
  • Version — whether the binary actually runs.

From a terminal or agent, request the same diagnostic from the affected daemon:

alp provider diagnostic <provider>
alp --host <host:port> provider diagnostic <provider> --json

Use the global --host option when the affected daemon is not the CLI's default local daemon.

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 alp's.

Fix it

The durable fix is to make sure the command is on PATH for a normal login shell, then restart alp, see why alp's environment can differ for why that's the test that matters.

If you'd rather pin it directly, set the binary path in $PASEO_HOME/config.json (~/.alp/config.json by default):

{
  "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, alp runs the binary directly, so use the path it points to. Reload the configuration after editing (see below).

For alternative endpoints, multiple profiles, custom binaries, and ACP agents, see Custom providers. For per-agent install links, see Supported providers.

Why alp's environment can differ from your terminal

The same mismatch shows up anywhere alp 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, alp 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, alp should too. That's also the test, open a fresh terminal and try it there.

When you start the daemon yourself from a terminal (alp), 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 alp. 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, alp 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 — ~/.alp/daemon.log ($PASEO_HOME/daemon.log if you've set a custom home).

Desktop app log location:

PlatformPath
macOS~/Library/Logs/alp/main.log
Linux~/.config/alp/logs/main.log
Windows%APPDATA%\alp\logs\main.log

I changed config.json but nothing happened

Reload the file after editing:

alp reload

alp applies runtime-safe settings and names any paths that require a restart. Invalid JSON or a schema error applies nothing; fix the reported error and run the command again. If a launch environment variable or flag owns a changed setting, reload reports it separately.

Run alp daemon restart only when reload requests it. In the app, open Settings → your host → Overview and use Restart daemon. Running agents keep going, and clients reconnect automatically.

Still stuck?