---
title: "S3 storage over MCP for your app, with while.sh"
url: https://while.sh/en/guides/store-files-s3/
author: "Aloïs Oddon, co-founder of Nextmap"
updated: 2026-11-02
---

# Store your app's files in an S3 bucket, from your AI agent

Do your users upload photos or PDFs? Ask your agent for a bucket: connected to while over MCP, it declares it in two lines, and your app connects to it with the AWS SDK.

## Prerequisites

- A Node.js, Python or Go app.
- An AI agent that works in a terminal: Claude Code, Codex, Cursor or Gemini CLI.

## Step 1: Give your agent these instructions

Open your agent in your app's folder and paste these instructions into it:

```text titre="Instructions"
Connect to while with my account (while.sh/agents), then deploy my app.
```

Your agent adds while's MCP server itself. If it asks you to, restart it. On the first call to while, a page opens in your browser. In Claude Code, if it doesn't open, type /mcp, choose while, then Authenticate. On that page, choose "A new app", then click Authorize.

## Step 2: Open your app

Your agent gives you your app's address, for example `https://mon-appli.while.cloud`, over HTTPS.

## What your agent does

It adds two lines to while.yaml:

```yaml titre="while.yaml"
apiVersion: while/v1
project: mon-appli
services:
  - name: web
    port: 3000
    health:
      path: /health
buckets:
  - name: uploads
```

The bucket's name reaches your app in `S3_BUCKET_UPLOADS`, the storage address in `S3_ENDPOINT` and its region in `S3_REGION`. Its key arrives where the AWS SDK looks for it on its own (source 1):

```js titre="server.js"
import { S3Client } from '@aws-sdk/client-s3';

const s3 = new S3Client({
  endpoint: process.env.S3_ENDPOINT,
  region: process.env.S3_REGION,
  forcePathStyle: true,
});
```

## Recover a file deleted by mistake

> You, to your agent: Bring back the invoice that was deleted yesterday.

The bucket keeps the old content of a replaced or deleted file for 30 days, and your agent puts it back.

## Keep the bucket's key secret

> You, to your agent: Give me the bucket's key.

Your agent never sees it: the key reaches only your app, in its variables.

## Add a database

> You, to your agent: Add a PostgreSQL database.

Your agent declares the database in while.yaml, and its address reaches your code in `DATABASE_URL`. It is backed up every day, and can go back to a precise moment if needed.

## Restrict your app to your colleagues

> You, to your agent: Restrict the app to people in the company.

Your agent adds two lines to the service:

```yaml titre="while.yaml"
    access: internal
    email_domains: [acme.com]
```

Once your Google Workspace or Microsoft 365 is connected to while, on the Pro plan, your colleagues open it with their usual account, and your code receives their name and email address, with no sign-in page to write.

## Go back to the previous version

> You, to your agent: Go back to the previous version.

In the 30 minutes after a deployment, the previous version comes back in a second. After that, it takes a few seconds. Once the previous version is back, your agent reads what broke in while's logs, fixes it and deploys again.

## Next steps

- [Deploy a Node.js API and its PostgreSQL database](/en/guides/deploy-node-api-postgresql/)
- [Add a Redis-compatible cache](/en/guides/add-redis-cache/)
- [Compare the hosts that have an MCP server](/en/comparisons/mcp-hosting-claude-code/)

## Sources

1. [AWS SDK for JavaScript v3, where the SDK looks for its credentials in Node.js (environment variables first)](https://docs.aws.amazon.com/sdk-for-javascript/v3/developer-guide/setting-credentials-node.html), 2026-11-02

## Questions

### How much does storage cost?

€0.25 per 10 GiB per month, requests included.

### Are my files encrypted?

Yes, and each bucket belongs to your organization alone.

### Which SDK do I use?

The AWS S3 SDK, or any S3-compatible client.