Skip to main content

Use with an AI Agent

A coding agent such as Claude Code, Cursor, or Codex can work with Fil One the same way any S3 client does. Fil One is S3-compatible, so the agent uses the AWS CLI or an AWS SDK it already knows. This guide covers how to give it access safely, and the few rules agents tend to get wrong against Fil One.

The console has a shorter version of steps 2 and 3, filled in for the region you pick: on the API Keys page, open the Connection details tab and go to the Use with an AI agent section, below Connect. Its profile commands don't store the endpoint, so its agent instructions give the endpoint directly. The steps below also store the endpoint in the profile, and keep the secret out of your shell history.

1. Create a key for the agent​

Give each agent its own key rather than reusing one from your application or your own machine. If the agent misbehaves or its key leaks, you can delete that key without breaking anything else.

When you create the key:

  • Name it after the agent and project, such as claude-code-reports, so the key list tells you what it is for.
  • Scope it to the buckets the agent needs. Choose Specific buckets rather than All buckets.
  • Make it read-only if the agent only reads. Keep Read and List, and untick Write, which is pre-selected. Leave Delete unticked unless the agent has to remove objects.
  • Pick the region the buckets are in. A key works in one region only.
  • Set an expiry, such as 30 days, for an agent you are trying out.

See API Keys for exactly what each permission allows.

2. Store the key in a profile​

Put the key in a named AWS CLI profile so the agent can use it without ever seeing it in a prompt or a file in your project.

First find your bucket's endpoint. The endpoint depends on the region the bucket is in, and the key has to be from that same region:

Bucket regionEndpoint
Europe (France) eu-west-1 (default)https://s3.eu-west-1.filonecontent.com
US East (Michigan) us-east-1https://s3.us-east-1.filonecontent.com

In the console you can copy it from the bucket's row on the Buckets page (Copy S3 endpoint in the actions menu), or from the Access endpoints block on the bucket's API Keys tab, which also shows the region. See Buckets.

Then run this yourself, in your own terminal, not through the agent, replacing <bucket_region> with the bucket's region:

aws configure set region <bucket_region> --profile filone
aws configure set endpoint_url https://s3.<bucket_region>.filonecontent.com --profile filone
aws configure set s3.addressing_style path --profile filone
aws configure --profile filone

The last command asks for the Access Key ID and Secret Access Key: paste each when prompted, then press Enter to keep the region and output format. It comes last so that pasting the whole block doesn't feed the other commands to the prompt as answers. The prompt keeps the secret out of your shell history, and the profile's endpoint_url (AWS CLI v2) sends requests to Fil One rather than to AWS. If you work in both regions, create one profile per region, such as filone-eu and filone-us.

Keep keys out of the agent's context

Don't paste a key into the chat, a system prompt, AGENTS.md, CLAUDE.md, or a .env file in the project. Agents read those files, and anything in them can end up in logs, commits, or the model's context. A profile keeps the secret in ~/.aws/credentials, outside the project.

An agent with shell access can still read ~/.aws/credentials if it tries. A profile keeps keys out of prompts and committed files, but the key's scope is what limits what the agent can do. Keep it narrow.

3. Add instructions for the agent​

Paste this into AGENTS.md, CLAUDE.md, or your agent's system prompt, and replace <bucket_region> with your bucket's region (eu-west-1 or us-east-1). It names the profile and never contains a key, so the file is safe to commit.

## Object storage: Fil One

Fil One is S3-compatible object storage. Use any S3 client.

- Region: <bucket_region>. The access key works in this region only.
- Endpoint: https://s3.<bucket_region>.filonecontent.com. The endpoint is region-specific: it must match the region of the bucket you address, and the key only works against its own region's endpoint. Don't use an AWS endpoint or another region's endpoint.
- Credentials and endpoint: the `filone` AWS profile. Pass `--profile filone` to the AWS CLI, or set `AWS_PROFILE=filone` for an SDK. Never print, log or commit the keys.
- Use path-style addressing; virtual-hosted-style URLs fail. The profile sets it for the AWS CLI and boto3. In JavaScript set `forcePathStyle: true`, in Go `UsePathStyle = true`.
- Send no server-side encryption headers. Data is already encrypted at rest. SSE-KMS requests are rejected; don't send SSE-C headers either.
- Creating or deleting buckets over S3 depends on the region. In eu-west-1 it is not supported: ask the user to create the bucket in the Fil One console. In us-east-1 it works only if the key has the Create bucket and Delete bucket permissions.
- Full reference: https://docs.filone.com/llms.txt

What agents get wrong​

Agents default to how Amazon S3 behaves. These are the differences that trip them up most:

What the agent doesWhat happensWhat to do instead
Uses virtual-hosted-style URLs (https://bucket.s3...), the default in most SDKsRequests failEnable path-style addressing in every client. See SDKs & Tools.
Sends ServerSideEncryption: aws:kms or SSE-C headersSSE-KMS is rejected in both regions. SSE-C is rejected in eu-west-1Send no encryption headers. Data is encrypted at rest automatically. See Encryption.
Calls CreateBucket or DeleteBucket in eu-west-1RejectedCreate and delete buckets in the console there. Both work over S3 in us-east-1. See Buckets.
Uses a key against the other region's endpointRequests failKeep the endpoint, the region, and the key in the same region.
Tries to turn versioning or Object Lock on or off after creating a bucketThe setting can't be changedBoth are set when the bucket is created. See Versioning.

For the full list of supported operations, see S3 Compatibility. Agents can read the whole of these docs as plain text at /llms.txt and /llms-full.txt.