Working with Files

File access in WingGate never exists outside the authorization chain. Every operation is bound to a Session, or to the MCP tool-call authorization chain (the Project grant and MCP configuration behind each tools/call). On an SSH / host asset the connection profile decides the remote OS user that the operation runs as, and WingGate does not maintain its own path ACLs — the target host's OS permissions for that user are the authority. On an SMB / WebDAV / S3 file backend, the target server's own share and object permissions are the authority.

Where file access lives

• Web Terminal file panel — browse and edit files on the asset of an active terminal session. The panel follows the shell's working directory for direct-shell sessions.
• MCP file tools — read / ls / fetch / upload / write / edit / mkdir / rename / delete / find / grep (aligned with Pi Hypa, no hypa_ prefix in MCP names) for AI agents, scoped to the Project's MCP configuration. See Setting up MCP access for credentials and client setup. The same tools serve both SSH / host assets and SMB / WebDAV / S3 file backends; the latter have no Web Terminal entry point and do not include find / grep.

Zero-install SFTP operations (SSH / host assets)

On an SSH / host asset, basic file operations — list, read, write, edit, mkdir, rename, delete — are fixed to a zero-install SFTP provider. They never require the Runner, never trigger its installation, and work as soon as the connection profile is valid:

• No extra component is installed on the asset for these operations.
• If SFTP is unavailable, the operation reports unavailable; it does not fall back to any other mechanism.

Process-free file backends (SMB / WebDAV / S3)

SMB shares, WebDAV sites and S3-compatible object storage are peer asset kinds: wing-connector speaks the target protocol directly, so file operations use no SFTP, need no Runner, and have no session or Web Terminal.

• The same file tools: these nine tools (ls, read, fetch, upload, write, edit, mkdir, rename, delete) share one contract, authorization chain, audit and error vocabulary with SSH assets. find / grep are not offered on these kinds — they rely on a Runner installed on the asset, and these assets have no host to install it on.
• Target and credential live in the asset: these kinds have no connection-profile layer; the target (share name / site URL / endpoint and bucket) and the credential reference belong to the asset itself. The credential stays a separate write-only record.
• The identity anchor differs per protocol: WebDAV requires HTTPS and a confirmed SPKI fingerprint before its tool group is enabled; SMB has no certificate to pin, so identity comes from SMB3's mandatory signing (binding the session key to the password) plus mandatory encryption, with NTLMv2 only and no downgrade option; the S3 endpoint is validated only by the public roots the HTTP client trusts, with per-request SigV4 for the request direction and no operator-confirmed identity fact.
• Object semantics are not POSIX: S3 has no directories — an empty directory is a zero-byte marker object; rename covers a single object only; delete never cascades; append is SMB-only. Do not infer WebDAV or S3 behaviour from SMB.

Runner-only search

Typed search is a different capability and requires the on-demand Runner:

• file.find matches paths by glob; file.grep searches file contents with literal substring by default, plus optional case-insensitive (ignoreCase) and Rust-regex (regex) matching.
• Traversal is ripgrep-like in scope: hidden entries and .gitignore/.ignore rules prune whole subtrees, so matches inside ignored directories never appear. To search an ignored path, point the root at a directory outside the ignore rules.
• The first use of a Runner-only operation creates a dedicated installation Job on the serving connector. The caller receives runner_installing; the console shows the Job's progress, and the original operation is retried automatically once the Runner binary is verified.
• Searches run under hard budget limits — directory entries, files read, bytes scanned, line length and recursion depth. When a budget is exhausted the search returns a budget-exhausted error; it never reports a fake partial success.
• Results are not a filesystem snapshot: changes between pages may omit, add or change matches. Clients that need a consistent view must re-run the search from the start.

Read and edit semantics

• File reads are byte-oriented: offset, limit and nextOffset are byte offsets, not line numbers. Reading is not a snapshot — if the file's hash changes between pages, re-read from the beginning.
• file.edit applies a set of non-overlapping replacements against the original file in one pass. Each oldText must match exactly once.
• Writes and edits return the hash of the file after the mutation, so callers can verify what actually landed.

Boundaries

• There is no unbounded bulk transfer: fetch/upload move whole small files up to a byte ceiling (max_file_bytes, 10 MiB by default), and everything else stays bounded and page-based. A transfer past the ceiling fails with file_too_large rather than truncating.
• File permissions on an SSH / host asset are decided solely by the connection profile's remote OS user: a profile that authenticates as root, or a passwordless-sudo profile, represents full host control and must be reviewed explicitly when granted. A file backend has no such layer — the target server's own share and object permissions decide.
• Every file operation is recorded in the Organization audit (session.file_operation) with the path, byte counts and outcome — never file content or search patterns — so file activity is attributable like any other session.

Troubleshooting

1. Read or list fails with an SFTP error on an SSH / host asset — confirm the connection profile's credential is still valid and the asset's connector is online.
2. runner_installing on a find or grep — wait for the installation Job; the operation retries automatically once the Runner is verified. If the Job fails, check the Runner artifact configuration with your WingGate service operator.
3. search_budget_exhausted — the query exceeded the scan budget. Narrow the path or pattern and retry; this is a permanent error, not a partial result.
4. Permission denied on the asset — the remote OS user cannot read or write that path. This is decided by the target host, not by WingGate; adjust the connection profile's user or the host's permissions.
5. WebDAV reports an unconfirmed certificate — probe the asset and confirm the SPKI fingerprint it reports; the asset's tool group stays disabled until then.
6. SMB / WebDAV / S3 reports unreachable — verify the target address and port from the network the wing-connector runs in, not from your laptop.
7. find / grep refused on a file backend — those two tools rely on a Runner installed on the asset and are not offered on these kinds; use ls and read instead.