Skip to main content
TencentVFS mounts one bucket: every object becomes a file and every / in a key a folder. It is the S3 VFS pointed at Tencent COS’s endpoint, so commands behave as they do on S3. Set up credentials as in Tencent COS setup.

Install

Configure

region also picks the endpoint, https://cos.<region>.myqcloud.com; endpoint replaces it. A mount takes MountMode.READ, WRITE or EXEC.

Fields

string
required
Name of the bucket to mount.
string
secret
Access key ID; set it with secretAccessKey. Unset uses the AWS SDK credential chain.
string
secret
Secret access key paired with accessKeyId.
string
secret
Session token for temporary credentials, sent with the access key pair.
string
Named profile in the shared AWS config and credentials files that supplies credentials when no access key pair is given.
boolean
Address the bucket in the URL path (<endpoint>/<bucket>/<key>) instead of as a subdomain of the endpoint.
string
Key prefix inside the bucket that the mount treats as its root; keys outside it are not visible. Leading slashes are dropped and a trailing / is added.
number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
string
secret
Proxy URL for every HTTP and HTTPS request to the endpoint.
string
required
Provider region every request is signed for. Most providers also build their endpoint URL from it unless endpoint is set.
string
Endpoint URL that replaces the one the provider derives.
Fields marked secret are redacted in snapshots.

Authentication

Credentials come from the first of:
  1. accessKeyId and secretAccessKey, with sessionToken for temporary credentials.
  2. profile, a profile in ~/.aws/credentials.
  3. The AWS SDK credential chain: environment variables, then the instance or container role.
accessKeyId takes the CAM SecretId and secretAccessKey the SecretKey. The sub-user needs a COS policy: read-only for a read mount, read and write for a write mount. An object the key may not read or change answers Permission denied.

Layout

/cos/reports/2026-q3.csv is the key reports/2026-q3.csv. Folders come from the / in keys.

Behavior

  • Key prefix: keyPrefix: 'users/42/' mounts only that part of the bucket, so /cos/notes.md is the key users/42/notes.md.
  • Bucket name: a COS bucket name ends in the account’s APPID, as in my-bucket-1250000000. bucket takes the full name, suffix included.

Browser

The browser TencentVFS from @struktoai/mirage-browser keeps the keys off the page: a server signs a URL for each S3 call with the Tencent COS keys, and the browser fetches it.
  • Requests go to the host each signed URL names; region and endpoint only name the mount’s storage location.
  • The bucket’s CORS rules must allow the page’s origin, exactly as served.
  • A browser mount cannot declare write: conditional, and any HTTP 403 from a signed URL, an expired one included, answers Permission denied.
  • keyPrefix set in the browser is no security boundary: enforce the prefix in the signing server and the key’s permissions.
An Express route that signs URLs:
Sign only the operations the app needs: a viewer needs GET, HEAD and LIST.
Set the rules in the console: COS > the bucket > Security Management > CORS. Allow the page’s origins, the methods GET, PUT, HEAD, DELETE and POST, the headers *, and expose ETag, Content-Length, Content-Type and Last-Modified.
string
required
Name of the bucket to mount.
function
required
secret
Function (path, operation, options) that returns a signed URL for each S3 operation; your server signs it, so the browser holds no keys.
string
Region of the bucket. Most providers derive the endpoint from it; requests go to the host each presigned URL names.
string
Endpoint URL that replaces the one the provider derives. Requests go to the host each presigned URL names; the mount uses it to name its storage location.
string
default:"'application/octet-stream'"
Content-Type stored with every object the mount writes.
string
Key prefix the mount treats as its root. The browser can change it before a URL is signed, so enforce the prefix on the signing server.
number
default:"DEFAULT_TIMEOUT"
Seconds a request may wait to connect, or between two reads of its answer, before it fails; a download that keeps flowing is never cut off.
Fields marked secret are redacted in snapshots.

Integration

Tencent COS answers these commands through its own API, so fewer objects are read. See Integration.
  • find: one recursive listing.
  • du: one recursive listing.
  • ls -R and tree: one recursive listing.

VFS.md

The VFS.md an agent reads with Tencent COS mounted at /<path>. <mode> is the mount’s mode: read, write or exec. The commands shown are those of a write mount.
Virtual FilesystemSupported Unix Commands for VFSUnix commands work on each path as on a local filesystem, as far as the path supports them:Limitations of Unix Commands for VFSWhere a path differs from a local filesystem:Run man <cmd> or <cmd> --help for one command’s usage.