Grexal Docs

File Upload

Accept credential files from users — SSH keys, service account JSON, certificates.

Status: Not yet implemented. You can declare file_upload connections in grexal.json and the CLI will accept them, but the platform currently refuses to run any agent that declares one. The reference below is kept for contract stability — agents written to this spec today will work unchanged once the mode ships. For now, use secret_input and paste the file contents into a text field.

For credentials that are files: SSH keys, service account JSON files, TLS certificates, configuration files.

Manifest declaration

{
  "connections": [
    {
      "id": "gcp_service_account",
      "display_name": "GCP Service Account",
      "auth_mode": "file_upload",
      "accepted_extensions": [".json"],
      "max_size_bytes": 65536,
      "description": "Upload your GCP service account key file (JSON format)"
    }
  ]
}

User experience

┌─────────────────────────────────────────────────┐
│  GCP Analyzer needs your GCP Service Account     │
│  key file.                                       │
│  Upload your GCP service account key file        │
│  (JSON format).                                  │
│                                                  │
│  [Choose file]  (.json, max 64 KB)               │
└─────────────────────────────────────────────────┘

Storage

The file contents are encrypted and stored in the vault as a base64-encoded blob. The file metadata (original filename, size, MIME type) is stored alongside.

Delivery

File credentials are always delivered via file injection. At sandbox creation, the platform writes the decrypted file to /tmp/grexal/{connection_id}/{original_filename}.

Agent code

async def run(ctx: AgentContext):
    sa_file = await ctx.connect("gcp_service_account")
    file_path = sa_file.get("file_path")
    # → /tmp/grexal/gcp_service_account/service-account.json

    from google.cloud import storage
    client = storage.Client.from_service_account_json(file_path)

Field reference

FieldTypeRequiredDefaultDescription
accepted_extensionsstring[]No—Allowed file extensions. Must start with a dot (e.g., ".json").
max_size_bytesnumberNo65536 (64 KB)Maximum file size. Platform max: 1,048,576 (1 MB).
descriptionstringNo—Instructions shown to the user in the upload prompt.
Manifest declarationUser experienceStorageDeliveryAgent codeField reference