strukto-ai--mirage/docs/python/resource/gcs.mdx

---
title: GCS
description: Mount Google Cloud Storage buckets through Mirage's async S3-compatible resource layer for Python agents.
icon: google
---
The GCS resource mounts a Google Cloud Storage bucket at some prefix
such as `/gcs/`. All operations involve network I/O to the remote object
store. Uses aioboto3 against GCS's S3-compatible XML API via HMAC keys,
inheriting all S3 resource capabilities.

For credential setup, see [GCS Setup](/home/setup/gcs).

## Config

```python
import os

from mirage import MountMode, Workspace
from mirage.resource.gcs import GCSConfig, GCSResource

config = GCSConfig(
    bucket=os.environ["GCS_BUCKET"],
    access_key_id=os.environ["GCS_ACCESS_KEY_ID"],
    secret_access_key=os.environ["GCS_SECRET_ACCESS_KEY"],
    # Optional:
    # endpoint_url="https://storage.googleapis.com",
    # region="auto",
    # timeout=30,
    # proxy="http://proxy:8080",
)
resource = GCSResource(config)
ws = Workspace({"/gcs": resource}, mode=MountMode.READ)
```

`GCSResource(config)` takes a `GCSConfig` object with the bucket name
and HMAC credentials. Both `READ` and `WRITE` modes are supported.

## Filesystem Layout

The GCS resource maps object keys to virtual paths under the mount
prefix, identical to the S3 resource. GCS "directories" are
prefix-based — there are no real directory objects.

For example, if bucket `mirage-ai` contains:

```text
data/example.json
data/example.parquet
data/example.jsonl
```

Then mounting at `/gcs/` exposes:

```text
/gcs/
  data/
    example.json
    example.parquet
    example.jsonl
```

Path mapping: virtual `/gcs/data/example.json` maps to GCS key
`data/example.json`.

## Cache

The GCS resource uses `IndexCacheStore` with `index_ttl = 600`
(10 minutes), same as S3. Directory listings are cached for up to 600
seconds before being refreshed from GCS. This reduces API calls for
repeated directory traversals.

## Example

```python
import asyncio
import os

from dotenv import load_dotenv

from mirage import MountMode, Workspace
from mirage.resource.gcs import GCSConfig, GCSResource

load_dotenv(".env.development")

config = GCSConfig(
    bucket=os.environ["GCS_BUCKET"],
    access_key_id=os.environ["GCS_ACCESS_KEY_ID"],
    secret_access_key=os.environ["GCS_SECRET_ACCESS_KEY"],
)

resource = GCSResource(config)


async def main() -> None:
    ws = Workspace({"/gcs/": resource}, mode=MountMode.READ)

    r = await ws.execute("ls /gcs/")
    print(await r.stdout_str())

    r = await ws.execute("cat /gcs/data/example.json | head -n 10")
    print(await r.stdout_str())

    r = await ws.execute("tree /gcs/")
    print(await r.stdout_str())

    r = await ws.execute("find /gcs/ -name '*.parquet'")
    print(await r.stdout_str())

    r = await ws.execute("stat /gcs/data/example.json")
    print(await r.stdout_str())


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

## Shell Commands

The GCS resource supports the full set of shell commands since it operates
on real file content (text, binary, JSON, CSV, etc.). Large files benefit
from range reads to avoid downloading entire objects.

### Read Commands

| Command         | Notes                                      |
| --------------- | ------------------------------------------ |
| `cat`           | Read file content                          |
| `head` / `tail` | First/last N lines                         |
| `grep` / `rg`   | Pattern search (file or directory level)   |
| `jq`            | Query JSON fields                          |
| `wc`            | Line/word/byte counts                      |
| `stat`          | File metadata (name, size, type, modified) |
| `find`          | Recursive search with `-name`, `-maxdepth` |
| `tree`          | Directory tree view                        |
| `nl`            | Number lines                               |
| `du`            | Disk usage summary                         |
| `file`          | Detect file type                           |
| `strings`       | Extract printable strings from binary      |
| `xxd`           | Hex dump                                   |
| `md5`           | MD5 checksum                               |
| `sha256sum`     | SHA-256 checksum                           |

### Text Processing

| Command    | Notes                                       |
| ---------- | ------------------------------------------- |
| `awk`      | Pattern scanning and processing             |
| `sed`      | Stream editor                               |
| `tr`       | Translate or delete characters              |
| `sort`     | Sort lines                                  |
| `uniq`     | Remove duplicate lines                      |
| `cut`      | Extract fields/columns                      |
| `join`     | Join lines on a common field                |
| `paste`    | Merge lines side by side                    |
| `column`   | Columnate output                            |
| `fold`     | Wrap lines to a specified width             |
| `expand`   | Convert tabs to spaces                      |
| `unexpand` | Convert spaces to tabs                      |
| `fmt`      | Simple text formatter                       |
| `rev`      | Reverse lines                               |
| `tac`      | Concatenate and print in reverse            |
| `look`     | Display lines beginning with a given string |
| `shuf`     | Shuffle lines                               |
| `tsort`    | Topological sort                            |
| `comm`     | Compare two sorted files                    |
| `cmp`      | Compare two files byte by byte              |
| `diff`     | Compare files line by line                  |
| `patch`    | Apply a diff patch                          |
| `iconv`    | Character encoding conversion               |

### File Operations

| Command  | Notes                                 |
| -------- | ------------------------------------- |
| `cp`     | Copy files                            |
| `mv`     | Move/rename files                     |
| `rm`     | Remove files                          |
| `mkdir`  | Create directories                    |
| `touch`  | Create empty file or update timestamp |
| `ln`     | Create symbolic links                 |
| `tee`    | Write stdin to file and stdout        |
| `mktemp` | Create temporary file                 |
| `split`  | Split file into pieces                |
| `csplit` | Split file by context                 |

### Path Utilities

| Command    | Notes                      |
| ---------- | -------------------------- |
| `basename` | Strip directory from path  |
| `dirname`  | Strip filename from path   |
| `realpath` | Resolve path               |
| `readlink` | Print symbolic link target |
| `ls`       | List directory contents    |

### Compression

| Command  | Notes                 |
| -------- | --------------------- |
| `gzip`   | Compress files        |
| `gunzip` | Decompress gzip files |
| `zip`    | Create zip archives   |
| `unzip`  | Extract zip archives  |
| `tar`    | Archive files         |
| `zcat`   | Cat compressed files  |
| `zgrep`  | Grep compressed files |

### Encoding

| Command  | Notes                |
| -------- | -------------------- |
| `base64` | Base64 encode/decode |

### Data Format Support

Commands with format-specific variants for structured data files:

| Format  | Extension  | Variants                                       |
| ------- | ---------- | ---------------------------------------------- |
| Parquet | `.parquet` | cat, head, tail, wc, stat, cut, grep, ls, file |
| Feather | `.feather` | cat, head, tail, wc, stat, cut, grep, ls, file |
| ORC     | `.orc`     | cat, head, tail, wc, stat, cut, grep, ls, file |
| HDF5    | `.hdf5`    | cat, head, tail, wc, stat, cut, grep, ls, file |

These variants auto-detect the format by extension and convert to
tabular text (CSV) for processing.

## Use Cases

- **AI agents accessing GCS data**: Mount GCS buckets for agents to read and process datasets
- **Data pipelines**: Read and write GCS objects with shell-like commands
- **FUSE mounting**: Expose GCS buckets through a virtual FUSE mount for external tools