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, 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 3600The 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 600Mount 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 --daemonWhat 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.