---
title: 'storage'
description: 'Operate the S3-style object store bound to a running agent installation: buckets, objects, uploads and presigned URLs.'
position: 19
---

# stackbone storage

> `stackbone storage` targets a **running agent installation**. With no
> `--agent` it uses the local-dev installation linked to the current project,
> so [`stackbone dev`](/docs/cli/reference/dev) must be running. See
> [target resolution](/docs/cli/reference/conventions#target-resolution).
> Every verb accepts `--json` and emits the
> [standard envelope](/docs/cli/reference/conventions#json-output).

Operate the S3-style object store bound to the targeted installation.
`--bucket <name>` is required on every object verb (an install can expose
more than one bucket).

| Command                           | Purpose                                                                                                      |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `stackbone storage buckets`       | List the buckets the installation exposes.                                                                   |
| `stackbone storage list`          | List objects in `--bucket`, optionally under `--prefix`. `--limit` is 1-1000 (default 100), with `--cursor`. |
| `stackbone storage get <key>`     | Download an object to stdout (or `--out <path>`) via a short-lived presigned URL.                            |
| `stackbone storage put <key>`     | Upload a local `--file <path>` under the key.                                                                |
| `stackbone storage presign <key>` | Print a short-lived presigned download URL for the object.                                                   |
| `stackbone storage remove <key>`  | Delete an object. Requires `--yes`.                                                                          |

`list` pages with `--limit`/`--cursor`, described under
[pagination](/docs/cli/reference/conventions#pagination). `remove` is
destructive and refuses to run without `--yes`, described under
[destructive verbs](/docs/cli/reference/conventions#destructive-verbs).

**JSON payload**

```jsonc
// storage list: paginated, plus folder prefixes
{ "schema_version": 1,
  "items": [{ "key": "uploads/foo.txt", "size": 1024, "content_type": "text/plain",
              "last_modified": "2026-06-01T10:00:00Z", "etag": "\"9a0364b9…\"" }],
  "common_prefixes": ["uploads/"], "nextCursor": null, "prevCursor": null }

// storage presign <key>
{ "schema_version": 1, "url": "https://…", "expires_at": "2026-06-01T11:00:00Z" }
```

**A presigned URL lasts one hour** and carries the address it was signed with.
`get` and `presign` both go through one, so the download works from your machine
only while that address resolves there. A box that keeps its objects in AWS S3
or Railway Buckets also needs `STACKBONE_S3_FORCE_PATH_STYLE=false` in its
`.env`: those backends put the bucket in a subdomain, and the default puts it in
the path (what the bundled MinIO speaks). See
[path-style or subdomain](/docs/sdk/data/storage#path-style-or-subdomain).

[`stackbone rag`](/docs/cli/reference/rag) manages the reserved `rag/` key
prefix: the backend rejects `put`/`remove` under it.

**Exit codes**: `0` ok · `4` not found (unknown bucket/key) · `5` permission
(`remove` without `--yes`) · `1` generic (missing `--bucket`/`--file`).
See [exit codes](/docs/cli/reference/conventions#exit-codes).