Skip to content
GroundboxDocs
API referenceStatusPricing
DashboardStart free
GroundboxGitHub Actions runners and Linux sandboxes for AI agents. One key, one bill.System status

Product

CI runnersSandboxesBuilds and cacheAgent computersPricing

Developers

DocsAPI referenceAPI explorerCLIMCP serverBenchmark

Compare

vs GitHub-hostedvs Blacksmithvs E2Bvs DaytonaAll comparisons

Company

Talk to usSupportcontact@groundbox.devGroundmail ↗
© 2026 Groundbox
TermsPrivacyllms.txt
OverviewCI in one lineFirst sandboxHand it to your agent
Sizes and labelsCachesBuild cachesMigrateci waitTerminal on a jobPublic repositoriesAuto sizeAuto size: own runnersFlexCI tune-upSplit tests by timeDocker buildsGitLab CI
Start, exec, filesFrom a Docker imageCommandsForkTime machineSnapshotsPause and resumeStop and startIdle pause and wakeScheduled runsPreviewsSecretsEgress allowlistFlex sandboxesTemplatesVolumes
Push and pullIn GitHub ActionsStorage and retention
Desktop and actionsLive view in your appHuman handoffSign in onceAgent loop example
BucketsAccess keysMount a bucket
Move from Runloop
Omnara
REST APIAPI explorerOpenAPI referenceCLIMCP serverSDKsKeys and capsLeave or delete a team
  1. Storage
  2. Storage
Markdown
Open in
ClaudeChatGPT
On this page

    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

    Terminal
    # 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)

    Python
    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)

    TypeScript
    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.

    Terminal
    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:

    Terminal
    # ~/.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.

    ← PreviousAgent computersNext →Move from Runloop
    System statusSupportPricingllms.txtgroundbox.dev