# Storage

S3-compatible buckets for agents and CI, with the same API key and balance as everything else. Files live on Groundbox's own servers. Any S3 client works: the aws CLI, boto3, the AWS SDKs, rclone. $0.015 per GB-month stored, billed by the hour; downloads and requests are free within fair use. Storage is on every plan; until a card is on file, a team stores up to 5 GB.

## Access keys

S3 clients sign each request with an access key id and a secret. Make one in the dashboard under [Storage](https://app.groundbox.dev/storage), with `groundbox storage keys create`, or with `POST /storage/access-keys` using an API key that has `storage:read` (read-only keys) or `storage:write`. The secret is shown once. A key made with an API key stops working when that API key is revoked or loses its storage scope; a key can be limited to some buckets.

## aws CLI

```
# An access key: the dashboard (Storage > New access key), or
groundbox storage keys create
export AWS_ACCESS_KEY_ID=GBX...
export AWS_SECRET_ACCESS_KEY=...
export AWS_ENDPOINT_URL_S3=https://storage.groundbox.dev
export AWS_REGION=auto

aws s3 mb s3://build-cache
aws s3 cp dist.tgz s3://build-cache/main/dist.tgz
aws s3 sync ./reports s3://build-cache/reports/
aws s3 ls s3://build-cache --recursive
aws s3 presign s3://build-cache/main/dist.tgz --expires-in 3600
```

The endpoint is path-style only (`https://storage.groundbox.dev/bucket/key`). Use any region name; `auto` is fine.

## Python (boto3)

```
import boto3
from botocore.config import Config

s3 = boto3.client(
    "s3",
    endpoint_url="https://storage.groundbox.dev",
    region_name="auto",
    aws_access_key_id="GBX...",
    aws_secret_access_key="...",
    config=Config(s3={"addressing_style": "path"}),
)
s3.upload_file("model.bin", "datasets", "v3/model.bin")  # multipart above 8 MB
for item in s3.list_objects_v2(Bucket="datasets", Prefix="v3/")["Contents"]:
    print(item["Key"], item["Size"])
```

## JavaScript (@aws-sdk/client-s3)

```
import { S3Client, PutObjectCommand, GetObjectCommand } from "@aws-sdk/client-s3";

const s3 = new S3Client({
  endpoint: "https://storage.groundbox.dev",
  region: "auto",
  forcePathStyle: true,
  credentials: { accessKeyId: process.env.AWS_ACCESS_KEY_ID!, secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY! },
});
await s3.send(new PutObjectCommand({ Bucket: "agent-notes", Key: "plan.md", Body: "# Plan" }));
const got = await s3.send(new GetObjectCommand({ Bucket: "agent-notes", Key: "plan.md" }));
console.log(await got.Body!.transformToString());
// Big files: Upload from @aws-sdk/lib-storage sends them in parts.
```

## groundbox CLI, SDKs and MCP

No access key needed: these use your API key. The SDKs have `list_buckets`, `create_bucket`, `list_objects`, `put_object`, `get_object`, `delete_object`, `presign_download_url`, `presign_upload_url` and `create_access_key`; the MCP server has the same as tools. Objects copied through the API are at most 32 MB each; use an S3 client for bigger ones.

```
groundbox storage mb s3://agent-notes
groundbox storage cp notes.md s3://agent-notes/
groundbox storage cp -r ./out s3://agent-notes/run-42/
groundbox storage ls s3://agent-notes
groundbox storage cp s3://agent-notes/notes.md -
groundbox storage presign s3://agent-notes/notes.md --expires 600
```

## Mount a bucket

rclone (or mountpoint-s3, or s3fs) can mount a bucket as a folder, in a sandbox or anywhere else. With rclone:

```
# ~/.config/rclone/rclone.conf
[groundbox]
type = s3
provider = Other
endpoint = https://storage.groundbox.dev
access_key_id = GBX...
secret_access_key = ...
region = auto
force_path_style = true

# Then: rclone ls groundbox:build-cache, or mount a bucket as a folder:
rclone mount groundbox:agent-notes /mnt/notes --vfs-cache-mode writes --daemon
```

## What the S3 API supports

- Buckets: list, create, head, delete (empty only), location.
- Objects: put, get (with ranges and conditionals), head, delete, delete many, copy, metadata (`x-amz-meta-*`), Content-MD5 and checksums (CRC32, CRC32C, CRC64NVME, SHA-1, SHA-256).
- Listing: ListObjectsV2 and ListObjects, with prefix, delimiter and pages.
- Multipart uploads: create, upload part, upload part copy, complete, abort, list parts, list uploads. Unfinished uploads are aborted after 7 days.
- Presigned GET and PUT URLs, valid for up to 7 days.
- Not supported: versioning, lifecycle rules, ACLs and bucket policies, tags, website hosting, public buckets, object lock, SigV2.

## Limits

- 1 TB per team by default, unfinished uploads included. Ask us for more.
- 100 buckets per team.
- One request body is at most 32 MB, so a single upload is at most 32 MB; the aws CLI and the SDKs send bigger files in parts on their own (up to 10,000 parts of 32 MB each).
- Spend caps apply: at a cap, or out of credit, uploads are refused; reading and deleting still work.

## Where your data is

Stored on NVMe drives in RAID 1 on one server in our rack. That survives a failed drive, not the loss of the server. We do not promise eleven nines: keep a copy elsewhere of anything you cannot afford to lose.
