# kio-s3

## Introduction

KIO S3 is a KIO worker that allows you to browse and manage files stored in Amazon S3 and S3-compatible storage services (such as Cloudflare R2, DigitalOcean Spaces, MinIO, and others) directly from Dolphin and other KDE applications.

With KIO S3, you can:

- Browse buckets and folders

- Upload and download files

- Copy, rename, and delete files and folders

- Create folders inside buckets

- Connect to multiple S3-compatible services at the same time using named profiles

## Configuring Profiles

KIO S3 supports connecting to multiple S3-compatible storage services through named profiles. Each profile stores the connection settings for one service. You can manage profiles in System Settings Network S3 Backends.

### Adding a Profile

Click the Add Profile... button and fill in the following fields:

Name

- A descriptive name for this profile (required), ⪚ `My Cloud Storage`.

Endpoint URL

- The URL of the S3-compatible service, ⪚ `https://s3.example.com`. Leave empty to use the default Amazon S3 endpoint.

Region

- The storage region, ⪚ `us-east-1` or `auto`. Leave empty to use the region from your AWS configuration.

AWS Profile

- The name of the credentials profile from `~/.aws/credentials`. If left empty, the profile identifier is used as the credentials profile name.

Use path-style S3 URLs

- Enable this for services that do not support virtual-hosted-style addressing, such as MinIO or some Ceph deployments. Most services, including Amazon S3 and Cloudflare R2, do not need this.

After adding a profile, click Apply to save. The new profile will appear as a shortcut in the Dolphin Places panel.

### Editing and Deleting Profiles

Each profile in the list has an edit and a delete action. Editing opens the same dialog with the current values pre-filled. Deleting asks for confirmation before removing the profile. Remember to click Apply to save your changes.

## AWS Credentials

KIO S3 uses the standard AWS credentials chain to authenticate with S3 services. Credentials are read from `~/.aws/credentials`, which can contain multiple named profiles:

    [default]
    aws_access_key_id = YOUR_KEY
    aws_secret_access_key = YOUR_SECRET

    [mycloud]
    aws_access_key_id = YOUR_CLOUD_KEY
    aws_secret_access_key = YOUR_CLOUD_SECRET

Each KIO S3 profile uses the AWS Profile field to select which credentials section to use. For example, a profile with AWS Profile set to `mycloud` will use the credentials from the `[mycloud]` section above.

If no profiles are configured, KIO S3 uses the default AWS credentials chain, which includes environment variables (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`), the `[default]` section in `~/.aws/credentials`, and EC2 instance roles.

You can optionally set the region using `~/.aws/config`:

    [default]
    region = eu-west-1

    [profile mycloud]
    region = auto

In `~/.aws/config`, named profiles use the `profile` prefix (⪚ `[profile mycloud]`), while in `~/.aws/credentials` the prefix is not used (⪚ `[mycloud]`). This is a convention of the AWS SDK.

## URL Scheme

KIO S3 uses the `s3://` URL scheme. You can type these URLs directly in the Dolphin location bar or use them with command-line tools such as `kioclient`.

`s3://`

- Lists all buckets available with the default AWS credentials.

`s3://`mybucket`/`

- Lists the contents of `mybucket`.

`s3://`mybucket`/`path/to/file.txt``

- Accesses a specific file in the bucket.

`s3://@`profile`/`

- Lists all buckets available on the named profile.

`s3://`mybucket`@`profile`/`

- Lists the contents of `mybucket` on the named profile.

`s3://`mybucket`@`profile`/`path/to/file.txt``

- Accesses a specific file on the named profile.

When you add a profile in System Settings, a shortcut is automatically created in the Dolphin Places panel. You can simply click it to browse that profile's buckets.

## Browsing Files

Open Dolphin and type `s3://` in the location bar to see your S3 buckets. Click a bucket to browse its contents. Folders and files appear just like on a local filesystem.

To browse a specific profile, type `s3://@`profile`/` or click the profile shortcut in the Places panel.

Navigation works as expected: you can use the breadcrumb bar, the back and forward buttons, and the location bar. You can also open S3 locations in new tabs.

## File Operations

### Uploading Files

Drag files from your local filesystem and drop them into an S3 folder in Dolphin. You can also use copy and paste. Large files are automatically uploaded using multipart upload to avoid excessive memory usage.

### Downloading Files

Drag files from an S3 folder to a local folder, or use copy and paste. You can also open S3 files directly in applications — the file will be downloaded to a temporary location and opened.

### Copying

You can copy files within the same S3 service using copy and paste or drag and drop. The copy is performed server-side, so it does not require downloading and re-uploading the file.

### Renaming

Press F2 in Dolphin to rename a file or folder. Since S3 does not have a native rename operation, KIO S3 performs a server-side copy to the new name and then deletes the original. For folders, all files inside the folder are copied and deleted individually.

### Deleting

Select files or folders and press Delete. When deleting a folder, all files and subfolders inside it are deleted recursively.

### Creating Folders

Press F10 or use Create New Folder... to create a new folder inside a bucket.

## Working with Multiple Profiles

If you use several S3-compatible services (for example, one for backups and another for website assets), you can configure a profile for each one and switch between them without changing any configuration files or environment variables.

Each profile appears as a separate shortcut in the Dolphin Places panel. Clicking a profile shortcut shows the buckets available on that service. All operations (upload, download, copy, rename, delete) work independently within each profile.

Copying or renaming files between different profiles is not supported. S3 server-side copy only works within a single service. To move files between profiles, copy them to a local folder first, then upload to the other profile.

## Known Limitations

- Bucket creation and deletion are not supported. Use the provider's web console or CLI tools to manage buckets.

- File permissions shown in Dolphin are cosmetic. S3 uses its own access control model (IAM policies and bucket policies), which does not map to Unix permissions.