Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mirage.strukto.ai/llms.txt

Use this file to discover all available pages before exploring further.

The SSH resource mounts a remote server’s filesystem over SFTP. It supports full read and write operations.

​
Config

from mirage import MountMode, Workspace
from mirage.resource.ssh import SSHConfig, SSHResource

config = SSHConfig(
    host="myserver",
    username="deploy",
    identity_file="~/.ssh/id_ed25519",
    root="/var/data",
)
resource = SSHResource(config=config)
ws = Workspace({"/remote": resource}, mode=MountMode.WRITE)
FieldRequiredDefaultDescription
hostyesSSH host (name or IP)
hostnamenoOverride resolved hostname
portno22SSH port
usernamenoSSH username
identity_filenoPath to private key
rootno/Remote directory to mount
timeoutno30Connection timeout in seconds
known_hostsnoPath to known_hosts file
The host field matches entries in ~/.ssh/config, so existing SSH configurations are automatically picked up.

​
Filesystem Layout

/remote/
  <remote-directory-tree>
The mounted tree mirrors the remote filesystem starting at root. Example with root="/var/data": 
/remote/
  logs/
    app.log
    nginx/
      access.log
      error.log
  config/
    app.yaml
  uploads/
    image.png

​
Cache

Uses IndexCacheStore for directory listings. Freshness is checked via {mtime}:{size} fingerprints - files are re-fetched only when the remote has changed.

​
Example

import asyncio

from mirage import MountMode, Workspace
from mirage.resource.ssh import SSHConfig, SSHResource

config = SSHConfig(
    host="myserver",
    username="deploy",
    identity_file="~/.ssh/id_ed25519",
    root="/var/log",
)
resource = SSHResource(config=config)


async def main():
    ws = Workspace({"/logs": resource}, mode=MountMode.READ)

    # List remote directory
    r = await ws.execute("ls /logs/")
    print(await r.stdout_str())

    # Read last 20 lines of a log
    r = await ws.execute("tail -n 20 /logs/nginx/access.log")
    print(await r.stdout_str())

    # Search across log files
    r = await ws.execute('grep "ERROR" /logs/app.log')
    print(await r.stdout_str())

    # Find large files
    r = await ws.execute("find /logs/ -name '*.log'")
    print(await r.stdout_str())

    # File metadata
    r = await ws.execute("stat /logs/app.log")
    print(await r.stdout_str())


if __name__ == "__main__":
    asyncio.run(main())

​
Shell Commands

CommandNotes
lsList remote files and directories
catRead remote file content
head / tailFirst/last N lines
grep / rgPattern search (use targeted paths)
wcLine/word/byte counts
statFile metadata (size, mtime)
findRecursive search with -name, -maxdepth
treeDirectory tree view
mkdirCreate remote directories
touchCreate empty remote files
cp / mv / rmCopy, move, delete on remote
teeWrite stdin to remote file
diff / cmpCompare remote files
sort / cut / trText processing
tar / zip / gzipCompression