> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://developers.alephant.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developers.alephant.io/_mcp/server. # MinIO > Configure the MinIO connector with a scoped S3-compatible access key and a narrow bucket prefix. Use the MinIO connector to index approved files from a MinIO bucket. AIvis connects through the S3-compatible API, lists objects under one prefix, downloads matching objects, and indexes supported file types. ## What You Need | Item | Requirement | | ------------ | --------------------------------------------------------------------------------------------------- | | Endpoint URL | Full MinIO API endpoint, such as `https://minio.example.com` or `https://minio.internal:9000`. | | Bucket | Existing MinIO bucket. | | Prefix | A non-empty prefix such as `knowledge/`. | | Credential | Access key and secret key with `s3:ListBucket` and `s3:GetObject` for the target bucket and prefix. | | Region | Optional. Fill it only if your MinIO deployment or proxy expects a specific region string. | | HTTP setting | Use HTTPS. Enable insecure HTTP only for a trusted internal development environment. | AIvis uses path-style S3 requests for MinIO. The endpoint must be an origin URL and must not contain credentials, query strings, or fragments. ## Prepare MinIO 1. Confirm the MinIO API endpoint is reachable from AIvis workers. 2. Use `mc alias set` to validate the endpoint and administrator credentials: ```bash mc alias set myminio https://minio.example.com MINIO_ADMIN_ACCESS_KEY MINIO_ADMIN_SECRET_KEY ``` 3. Create or identify a bucket, for example `aivis-docs`. 4. Upload approved documents under a dedicated prefix, for example `knowledge/`. 5. Create a scoped policy and access key for AIvis. Do not use root credentials. ## Minimum MinIO Policy The built-in MinIO `readonly` policy does not include bucket listing. AIvis must list objects under the configured prefix, so create a custom policy that allows `s3:ListBucket` for the bucket and `s3:GetObject` for the prefix. ```json { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "s3:ListBucket" ], "Resource": [ "arn:aws:s3:::aivis-docs" ], "Condition": { "StringLike": { "s3:prefix": [ "knowledge/", "knowledge/*" ] } } }, { "Effect": "Allow", "Action": [ "s3:GetObject" ], "Resource": [ "arn:aws:s3:::aivis-docs/knowledge/*" ] } ] } ``` Example `mc` flow: ```bash mc admin policy create myminio aivis-knowledge-readonly ./aivis-knowledge-readonly.json mc admin user add myminio aivis-reader '' mc admin policy attach myminio aivis-knowledge-readonly --user aivis-reader ``` If you use service accounts or access keys for an existing user, attach an equally scoped policy to that key. The key cannot grant more access than the parent user is allowed to use. ## Credential Fields Create a MinIO credential in AIvis: | AIvis Field | Value | | ------------------------------ | ------------------------------------------------------------------------------------------ | | Key ID / Access Key ID | MinIO access key for the scoped user or service account. | | Secret key / Secret Access Key | Secret key paired with that access key. | | Session Token | Usually empty. Fill it only if your deployment issues temporary S3-compatible credentials. | ## Connector Fields | AIvis Field | Example | Notes | | --------------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------------ | | Connector name | `MinIO knowledge` | Use a name that identifies the deployment and bucket scope. | | Bucket Name | `aivis-docs` | Bucket name only. | | Prefix | `knowledge/` | Must be non-empty. AIvis removes leading `/`. | | Endpoint URL | `https://minio.example.com` | Required. Include scheme and optional port. | | Region | `us-east-1` or empty | Optional. Keep empty unless required by your MinIO configuration. | | Allow insecure HTTP | Off | Turn on only for trusted internal development endpoints such as `http://minio:9000`. | | ACL limitation confirmation | Checked | MinIO policies and object ACLs are not synchronized into AIvis search permissions. | | Document access | Prefer **Private** and assign users or groups. | Split prefixes/connectors by audience. | ## Verify 1. Confirm the credential validates. 2. Create the connector for a small prefix such as `knowledge/test/`. 3. Run one index attempt and confirm only objects under that prefix appear. 4. Search for a known sentence from an uploaded file. 5. Confirm unselected prefixes and sensitive files are absent. 6. Test as an unauthorized AIvis user and confirm private connector content is not searchable. ## Troubleshooting | Symptom | Likely cause and action | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Endpoint is rejected | Endpoint is missing `https://`, contains credentials/query/fragment, or uses HTTP without enabling **Allow insecure HTTP**. | | Credential is invalid | Access key and secret key do not match, are disabled, or belong to a user without the scoped policy. | | Objects cannot be listed | Policy is missing `s3:ListBucket` on the bucket, or the `s3:prefix` condition excludes the configured prefix. | | Objects are listed but cannot be read | Policy is missing `s3:GetObject` for `bucket/prefix/*`. | | Connection works with `mc` but not AIvis | Confirm the endpoint is reachable from AIvis workers, not only from your laptop. Check DNS, TLS certificate trust, ports, and private-network policy. | | Users can search files they should not access | MinIO policies are not synchronized to AIvis. Use private document access or split connectors by audience. | ## Related Official Documentation * [MinIO Client quickstart](https://minio.github.io/mc/) * [MinIO policy-based access management](https://min.io/docs/minio/linux/administration/identity-access-management/policy-based-access-control.html) * [MinIO `mc admin policy`](https://min.io/docs/minio/linux/reference/minio-mc-admin/mc-admin-policy.html) * [MinIO `mc admin accesskey create`](https://min.io/docs/minio/linux/reference/minio-mc-admin/mc-admin-accesskey-create.html)