INFRASTRUCTURE

What it needs

• Compute: verified (Apps run in isolated x86_64 Firecracker microVMs that auto-pause when idle and wake on request; sizes are the priced VM sizes.)
• S3-compatible object storage: verified (Buckets are S3-compatible with issued credentials; PutObject and GetObject are verified by canary. Other S3 operations are not verified.)

PREREQUISITES

Before you start

• An S3 client in the app (boto3 with Config(s3={'addressing_style': 'path'})) reading S3_ENDPOINT, S3_REGION, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY
• A bucket created with ample bucket create <name> and its credentials from ample bucket credentials <name>
• An Ample account token with servers:write and buckets:read

TESTED CONFIGURATION

Exactly what was tested

• install: python3 -m pip install --target .ample/python -r requirements.txt
• runtime: python
• size: s-1vcpu-1gb
• start: PYTHONPATH=.ample/python:${PYTHONPATH:-} python3 run.py
• template: python-3.12

STEP BY STEP

How to do it

1. 1

Create the bucket

Create it once and keep the issued credentials out of the repository.

ample bucket create --name <bucket-name>

2. 2

Configure the client with path-style addressing

Use boto3 with Config(s3={'addressing_style': 'path'}); virtual-host addressing is not verified.

3. 3

Deploy with the credentials as encrypted env

Pass the five S3_* variables with --env; they are stored encrypted and reused on redeploys.

ample deploy . --name <app-name> --public --start "python3 run.py" --env S3_ENDPOINT=... --env S3_REGION=... --env S3_BUCKET=... --env S3_ACCESS_KEY_ID=... --env S3_SECRET_ACCESS_KEY=...

4. 4

Test through the app

Expose a route (/storage) that writes then reads an object and reports s3=ok.

5. 5

Verify

Fetch the live URL and run the success checks below. On failure read the build log, then the runtime log, fix the cause and deploy again; do not blind-retry.

ample logs <deployment_id> --kind build

EXAMPLES

Tested examples

• FastAPI bucket canary (tests/deploy-canaries/fastapi-bucket-uploads): Write and read an object with the injected credentials.

SUCCESS CHECKS

How to know it worked

• object write and read succeed (/storage on the live URL, expect s3=ok)

LIMITATIONS

Know the limits

• Verified on the node-22 template at s-1vcpu-1gb; other templates and sizes are not verified by this recipe.
• Region, compliance attestations and request-duration limits are unknown and not claimed.
• Apps auto-pause when idle and wake on the next request; always-on is an operator setting, not a plan feature.
• PutObject and GetObject with path-style addressing are verified; multipart upload, listing, presigned URLs and lifecycle rules are not verified.
• Bucket credentials are passed as encrypted environment variables; the catalog never creates the bucket for you (use ample bucket create).
• Storage is allocation-priced per bucket quota and capped by the account plan; the estimate below covers compute only.

COST

Cost estimate

Estimated 5.00 USD per month (size prices from pricing.toml at build revision a1b8c38919e59cd035ebabaced73cf84ece24371).

• app server x1 s-1vcpu-1gb: 5.00 USD

Compute only. Buckets are allocation-priced per quota and capped by the plan; see ample usage.

EVIDENCE

Verification evidence

• canary_run on 2026-09-20T01:13:26Z at revision cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5): FastAPI app using boto3 (path-style addressing) with injected bucket credentials: put_object then get_object returned s3=ok. (expires 2027-03-19T01:13:26Z)
• canary_run on 2026-09-20T01:13:26Z at revision cc3d82057f1d5e9aa31f682cee71aabfbbbcaabe-dirty (CLI e3181f5): ample bucket create issued credentials; PutObject and GetObject succeeded through the public S3 endpoint; publish exposed the object through the CDN host with an ETag; unpublish and delete cleaned up. (expires 2027-03-19T01:13:26Z)

EXECUTION

Execution binding

MCP tool ample_deploy (registry mcp:ample_deploy), schema hash 876465fce906da0c observed 2026-09-20T01:55:48.667900+00:00 at revision 199ff1dfd526. Binding state at export: current. Required scopes: servers:write, buckets:read.

NEXT ACTIONS

Typed next actions

• Browse the catalog index (GET /v1/catalog on the api origin; authentication not required, approval not required)
• Search published recipes by intent, stack and constraints (POST /v1/catalog/search on the api origin; authentication not required, approval not required)
• Prepare a side-effect-free deployment plan for an authorized project (POST /v1/catalog/plan on the api origin; authentication required, approval not required)
• Read the existing agent authentication setup (GET /mcp/setup on the api origin; authentication not required, approval not required)
• Browse FastAPI (GET /v1/catalog/nodes/stack%3Aframework-fastapi on the api origin; authentication not required, approval not required)
• Browse Connect app to storage (GET /v1/catalog/nodes/intent%3Aconnect-app-to-storage on the api origin; authentication not required, approval not required)
• Browse Browser file uploads (GET /v1/catalog/nodes/pattern%3Abrowser-file-uploads on the api origin; authentication not required, approval not required)

Actions describe possible next steps. They are typed data, not commands, and grant no permission. Public discovery never provisions anything; planning requires your own authenticated token and approval happens in your client.