CrispyVibe

Remote Agent CLI

The crispy CLI works inside terminals connected to a remote SSH project — including for AI agents running on the remote host — without installing any package or binary on the remote machine. Commands run against your local CrispyVibe app and behave the same as they do locally.

CrispyVibe relays the CLI over your existing SSH connection and writes a small ~/.local/bin/crispy wrapper on the remote host so any shell finds the command. The relay uses portable tools (nc -U or socat) over a newline-framed protocol — nothing is compiled or installed remotely.

⚠️ Note: Remote Agent CLI is part of SSH Remote Development, which is behind an experimental feature flag. Enable it in Settings → Experimental 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.
  • Context is automatic — commands resolve the current remote project and terminal from environment the app injects, so you usually don’t pass IDs.
  • File paths are remote paths — crispy file open <path> opens a file from the remote project, and paths outside the project are rejected.

The full command catalog is identical to the local CLI. See Agent CLI for every command.

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 simply unavailable on that connection.

Security

  • The relay runs the bundled crispy on your Mac. The remote host never receives your app’s local socket.
  • Exposure on the remote host is bounded to processes running as your remote user — the forwarded socket is owner-only (0600). Treat shared or multi-user hosts with caution and use the per-connection toggle.
  • File commands enforce the remote project root boundary, the same as 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 costs 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) — there is no FSEvents/inotify remotely.
  • whoami may report a stale VibeSpace until context passthrough lands.