Resources

Files and directories on the host, by file:// URI. The URI is a path on the host, not on the machine running ahpc.

Screen

f in a session opens the files in its workspace. @ in the composer completes a path on the host.

Commands

Command		Flags
resource list <uri>	A directory	--json
resource read <uri>	A file, to stdout
resource stat <uri>	Its type and size, without reading it	--json
resource write <uri> [file]	Write it, from a file or from stdin	--create-only --force
resource rm <uri>	Delete a file or directory	--recursive
resource mkdir <uri>	Make a directory
resource mv <uri> <to>	Move or rename	--fail-if-exists
resource cp <uri> <to>	Copy	--fail-if-exists

ahpc resource read file:///work/api/README.md
echo "notes" | ahpc resource write file:///work/api/NOTES.md

A write is refused when the file changed since ahpc read it, so two clients cannot overwrite each other. --force writes anyway.

MCP tools

Served with --mcp-tools resources.

Tool	What it does	Arguments
list_directory resources, read only	What is in a directory the host serves. Takes a file:// URI on the host.	pathstring, required A file:// URI of a directory on the host.
read_file resources, read only	The contents of a file the host serves. Text comes back as text; anything the host sends as bytes comes back base64 with the encoding said.	pathstring, required A file:// URI on the host.
write_file resources	Write a file on the host, refusing if it changed since it was read. Pass force to write over whatever is there now. A host that has not granted write access to that directory refuses this, and only a person at the host can grant it.	pathstring, required A file:// URI on the host. contentstring, required The whole new contents. This replaces the file. createOnlyboolean Refuse if the file already exists. forceboolean Write even if the file changed since it was last read.
make_directory resources	Create a directory on the host.	pathstring, required
delete_path resources	Remove something on the host. A directory needs recursive.	pathstring, required recursiveboolean Needed to remove a directory that is not empty.
move_path resources	Move something on the host, which is also how it is renamed.	fromstring, required tostring, required failIfExistsboolean Refuse rather than write over something already at the destination.
copy_path resources	Copy something on the host.	fromstring, required tostring, required failIfExistsboolean Refuse rather than write over something already at the destination.

Publish a folder to the host

A host can also read files from the client. ahpc shares nothing until --publish names a folder:

ahpc --host ws://127.0.0.1:9187 --publish ~/notes

Flag
--publish <dir>	Share this folder, read only
--publish-writable	Let the host write to it too

The host reads the files at virtual://<clientId>/<path>. The folder is shared only while the screen is open.

Host support

The host decides which directories it serves and which a client may write to. A write it does not allow is refused with -32009.