> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ancha.io/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These docs describe the Ancha CLI, npm package @ancha-labs/cli version 0.1.4, and the hosted workspace at app.ancha.io. Coding agents should start at https://docs.ancha.io/coding-agents. Run the CLI as `ancha` after `npm install -g @ancha-labs/cli`, or as `npx -y @ancha-labs/cli@0.1.4` without installing. Pass --json for machine-readable output, or set ANCHA_JSON=1. Every command ends with a `next:` line naming the next command. Exit codes: 0 pass, 1 a check failed or a comparison regressed, 2 usage, config or authentication error, 3 infrastructure error, 4 unimplemented endpoint with --strict.

# Amazon S3

> A stateful replica of the Amazon S3 REST API with SigV4: buckets, objects, tags, conditional writes, checksums and multipart uploads for one account.

The Amazon S3 replica implements 25 operations of the S3 REST API for one account, with path-style addressing. Its key is `amazon-s3`. It was tested with `@aws-sdk/client-s3`.

## Connect

| Variable | Value |
| - | - |
| `AWS_ENDPOINT_URL_S3` | The endpoint. The SDK reads it itself. |
| `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` | Fake credentials for the account's one access key. Requests are signed with SigV4 as usual. |
| `AWS_REGION` | `us-east-1`, the region of every starter bucket except `acme-backups`. |

```js Node theme={null}
import { S3Client, ListBucketsCommand } from '@aws-sdk/client-s3';
const s3 = new S3Client({ endpoint: process.env.AWS_ENDPOINT_URL_S3, forcePathStyle: true });
const { Buckets } = await s3.send(new ListBucketsCommand({}));
```

This is what `ancha connect amazon-s3 --lang ts` prints. The replica is one endpoint, so use path-style addressing: the SDK chooses it for an IP endpoint; set `forcePathStyle` for a host name.

## Operations

| Operation | Request | Notes |
| - | - | - |
| ListBuckets | `GET /` | `max-buckets`, `continuation-token`, `prefix` and `bucket-region`. |
| CreateBucket | `PUT /{Bucket}` | `LocationConstraint` must match the signing region. Names other accounts own answer `BucketAlreadyExists`. ACLs are disabled. |
| HeadBucket, DeleteBucket | `HEAD`, `DELETE /{Bucket}` | |
| GetBucketLocation | `GET /{Bucket}?location` | |
| GetBucketTagging, PutBucketTagging, DeleteBucketTagging | `/{Bucket}?tagging` | |
| ListObjectsV2 | `GET /{Bucket}?list-type=2` | `prefix`, `delimiter`, `max-keys`, continuation tokens, `start-after`, `fetch-owner`, `encoding-type=url`. |
| ListObjects | `GET /{Bucket}` | |
| DeleteObjects | `POST /{Bucket}?delete` | Up to 1,000 keys. Requires `Content-MD5` or an `x-amz-checksum` header, as S3 does. |
| PutObject | `PUT /{Bucket}/{Key+}` | Verifies `Content-MD5` and CRC32, CRC32C, SHA-1 and SHA-256 checksums. `If-None-Match: *` and `If-Match` conditional writes. User metadata and tagging. |
| CopyObject | `PUT /{Bucket}/{Key+}` with `x-amz-copy-source` | `COPY` or `REPLACE` metadata and tagging directives. Conditional copy headers are gaps. |
| GetObject | `GET /{Bucket}/{Key+}` | Single byte ranges, conditional reads, `response-*` overrides, checksum mode. Glacier objects answer `InvalidObjectState`. |
| HeadObject, DeleteObject | `HEAD`, `DELETE /{Bucket}/{Key+}` | Unversioned buckets only. |
| GetObjectTagging, PutObjectTagging, DeleteObjectTagging | `/{Bucket}/{Key+}?tagging` | |
| CreateMultipartUpload | `POST /{Bucket}/{Key+}?uploads` | |
| UploadPart | `PUT /{Bucket}/{Key+}?partNumber&uploadId` | |
| ListParts, AbortMultipartUpload | `GET`, `DELETE /{Bucket}/{Key+}?uploadId` | |
| CompleteMultipartUpload | `POST /{Bucket}/{Key+}?uploadId` | Parts other than the last must be at least 5 MiB. |
| ListMultipartUploads | `GET /{Bucket}?uploads` | |

All 25 operations are partial. Anything else returns HTTP 501 with S3's XML error shape and `x-ancha-gap: 1`.

## Behavior

* **One account**, `acme-production` (`481516234200`), with one access key for the user `ancha-agent`. Each bucket grants that key read-write, read-only or no access, which stands in for IAM policies.
* **Bucket names** such as `test`, `data`, `backups`, `logs`, `uploads` and `reports` are taken by other accounts.
* **Presigned URLs** are verified but never expire.

## Starter data

The `amazon-s3-starter` dataset has four buckets.

| Bucket | Region | Access | Contents |
| - | - | - | - |
| `acme-exports` | us-east-1 | read-write | Customer exports under `exports/<customer>/<period>/`: Ridgeway Robotics orders and shipments for June (in `GLACIER`), August and September, Kestrel Credit Union daily rollups for 2026-10-29 (with doubled rows) and 2026-10-30, Pinecrest Health seats, Summit Freight active users, and a `README.txt` describing the layout. Objects carry `customer` and `retention` tags. |
| `acme-warehouse-staging` | us-east-1 | read-only | The Ridgeway Robotics sync for 2026-10-31: `_manifest.json` and JSON Lines parts for orders and shipments. |
| `acme-backups` | us-west-2 | none | Two nightly database dumps. Every request fails with access denied. |
| `acme-web-assets` | us-east-1 | read-write | Release `2026.10.29`: `manifest.json`, `app.js` and `app.css` with `Cache-Control` headers. |

## Checks

Amazon S3 has no state checks. Use trace checks on path-style requests, for example `{ called: "PUT /acme-exports/exports/*" }` or `{ not_called: "DELETE /acme-exports/*" }`.

## Limits

* No versioning, object lock, ACLs, KMS encryption, Glacier restores or event notifications.
* One account and one access key; per-bucket access instead of IAM.


## Related topics

- [Tools](https://docs.ancha.io/tools/overview.md)
- [Test file (scene.yaml)](https://docs.ancha.io/reference/test-file.md)
- [Introduction](https://docs.ancha.io/index.md)
- [ancha connect](https://docs.ancha.io/cli/connect.md)
- [Environment variables](https://docs.ancha.io/reference/environment-variables.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.