ashpipe

ashpipe

cd into a directory, get an SSH session — for humans and AI agents.

cd workspace/remote-space-prod/   →   terminal becomes a remote SSH session

ashpipe turns a local directory into a transparent portal to a remote host. File access goes through SSHFS (you see real remote files), and the terminal pty is handed directly to the remote shell. For AI agents (Claude Code, Codex), mounted portal directories are ordinary local directories, so built-in file tools can read, edit, diff, and search without switching to ashpipe-specific tools.

Safety warning

Do not manually delete ashpipe portal paths or mount directories with rm -rf. ashpipe manages them. Use ashpipe unmount and ashpipe remove instead.

If you must clean anything manually, unmount first and verify it is no longer a mount point:

ashpipe unmount <portal>
mount | grep ashpipe

Deleting a live SSHFS/FUSE mount can delete files on the remote host.

How it works

workspace/
├── .ashpipe/
│   └── config.yaml          ← host and portal definitions
├── remote-space-prod -> /Volumes/ashpipe/<workspace-id>/remote-space-prod      # macOS
└── remote-space-dev  -> /media/$USER/ashpipe/<workspace-id>/remote-space-dev   # Linux

The real SSHFS mount points live outside the workspace (for example under /Volumes/ashpipe on macOS or /media/$USER/ashpipe on Linux). This mirrors where external drives normally appear, making it clear that the portal target is a mounted filesystem. It also keeps rm -rf remote-space-prod and rm -rf .ashpipe from recursing into remote files.

User path — shell hook detects portal directory on cd, mounts SSHFS, hands terminal to remote shell. On exit, SSHFS is automatically unmounted.

Agent path — ashpipe mount mounts portal directories via SSHFS without starting an interactive SSH shell. Agents then use their default built-in file tools directly against the mounted directory.

Both paths are system-native: humans get a remote pty, agents get real mounted directories.

Requirements

Platform	SSHFS	Notes
macOS	macFUSE + brew install sshfs	macFUSE requires manual install (kernel extension)
Linux	sudo apt install sshfs	or dnf install fuse-sshfs / pacman -S sshfs
NixOS	provided by flake.nix dev shell	see below

SSH host must already be in ~/.ssh/known_hosts. Connect manually once if not:

ssh user@hostname

Nix / NixOS

ashpipe ships a flake.nix with full cross-platform support (Linux x86_64/aarch64, macOS aarch64/x86_64).

# Enter dev shell (provides go, sshfs, gopls, gotools)
nix develop

# Build the binary
nix build
./result/bin/ashpipe --help

Shell hook via home-manager (do not echo directly into ~/.zshrc on managed systems):

programs.zsh.initExtra = ''
  eval "$(ashpipe hook zsh)"
'';
# or for bash:
programs.bash.initExtra = ''
  eval "$(ashpipe hook bash)"
'';

Package — add to your NixOS configuration.nix or home.nix:

# flake input
inputs.ashpipe.url = "github:KirisameLonnet/ashpipe";

# package
environment.systemPackages = [ inputs.ashpipe.packages.${system}.default ];
# or with home-manager
home.packages = [ inputs.ashpipe.packages.${system}.default ];

On macOS with Nix, macFUSE cannot be managed by Nix (kernel extension). Install it separately:

1. Download from osxfuse.github.io and install
2. brew install sshfs

On NixOS, sshfs is included in the dev shell and available as pkgs.sshfs-fuse.

Install

Once installed via any method below, the hook just works — no full path needed:

eval "$(ashpipe hook zsh)"   # or bash / fish

Homebrew

brew install KirisameLonnet/tap/ashpipe

Arch Linux

The repository includes an Arch PKGBUILD under packaging/aur/ for ashpipe-bin. Clone the repository and build it locally:

git clone https://github.com/KirisameLonnet/ashpipe.git
cd ashpipe/packaging/aur
makepkg -si

Nix / home-manager

# flake.nix
inputs.ashpipe.url = "github:KirisameLonnet/ashpipe";

# home.nix
home.packages = [ inputs.ashpipe.packages.${system}.default ];
programs.zsh.initExtra = ''
  eval "$(ashpipe hook zsh)"
'';

Debian / Ubuntu (.deb)

# Download from https://github.com/KirisameLonnet/ashpipe/releases
sudo dpkg -i ashpipe_*_amd64.deb
# or for arm64:
sudo dpkg -i ashpipe_*_arm64.deb

Fedora / RHEL / openSUSE (.rpm)

sudo rpm -i ashpipe_*_amd64.rpm
# or for arm64:
sudo rpm -i ashpipe_*_arm64.rpm

Go

go install github.com/KirisameLonnet/ashpipe@latest

Build from source

git clone https://github.com/KirisameLonnet/ashpipe
cd ashpipe
go build -o ashpipe .
# Move to somewhere in your PATH, e.g.:
sudo mv ashpipe /usr/local/bin/

Quick start