CrispyVibe

Remote Agent CLI

The crispy CLI works in terminals connected to a remote SSH project, including for AI agents running on the remote host. It requires no package or binary installation on that host. Commands run against your local CrispyVibe app and behave as they do in local terminals.

CrispyVibe relays the CLI over your existing SSH connection and writes a small ~/.local/bin/crispy wrapper on the remote host so shells can find the command. It does not compile or install software remotely.

⚠️ Note: Remote Agent CLI is part of SSH Remote Development. Set up an SSH project first.

Prerequisites

  • An SSH project you can connect to (see SSH Remote Development)
  • nc (with -N) or socat available on the remote host
  • SSH forwarding permitted on the host (AllowStreamLocalForwarding / AllowTcpForwarding)
  • ~/.local/bin on your remote login PATH (the default on Ubuntu via ~/.profile)

Enabling the relay

  1. Open Settings > Connections and edit your SSH profile.
  2. Confirm Allow Agent CLI (crispy) on this connection is on. It is enabled by default.
  3. Connect to the remote project and open a terminal.

Verifying it works

  1. In a remote terminal, run crispy ping.
  2. You should see the app version, confirming the relay is active.

Agents can run it the same way, for example bash -lc "crispy whoami --json".

How agents use it

  • An agent running on the remote host calls crispy, for example crispy whoami or crispy file open src/app.ts, and reads the result from standard output like any other CLI.
  • Commands resolve the current remote project and terminal from environment variables, so you usually don’t pass IDs.
  • File arguments use remote paths. crispy file open <path> opens a file from the remote project, and paths outside the project are rejected.

The remote CLI supports the same command catalog as the local CLI. See Agent CLI for the commands.

Per-connection control

Each SSH profile has its own Allow Agent CLI (crispy) on this connection toggle in Settings > Connections. Turn it off for shared or untrusted hosts; crispy is then unavailable on that connection.

Security

  • The relay runs the bundled crispy on your Mac. The app’s local control socket is never exposed to the remote host.
  • The forwarded socket is owner-only (0600), limiting access to processes running as your remote user. Treat shared or multi-user hosts with caution and use the per-connection toggle.
  • File commands enforce the remote project root boundary as they do for local commands.

Troubleshooting

IssueSolution
crispy: command not foundEnsure ~/.local/bin is on your remote login PATH, then reopen the terminal so the wrapper is written.
crispy: IDE relay unavailableThe host disallows SSH forwarding, the connection dropped, or nc/socat is missing. The rest of your shell keeps working. Reopen the terminal or enable forwarding.
Command hangsReconnect the remote project. The relay half-closes with nc -N, so this should not normally happen.

Known limitations

  • Requires SSH forwarding permitted and nc/socat present on the remote host.
  • Each command adds one SSH round-trip of latency because the relay runs the bundled crispy on your Mac.
  • A remote file open in the editor auto-reloads on external change via polling, roughly every 4 seconds. Remote hosts do not use FSEvents/inotify.
  • whoami may report a stale VibeSpace.