Skip to main content

Use your own object storage

Stairway can save a browser session's downloads, HAR captures, and state snapshots to an S3-compatible bucket that you control. AWS S3, MinIO, RustFS, and other S3-compatible services are supported.

If you do not select a profile, the session continues to use Stairway's platform storage.

Add and test a profile​

  1. Open Settings (/settings).
  2. Under Object storage, choose Add profile.
  3. Enter:
    • a label;
    • the S3 API endpoint and bucket;
    • the region and optional bucket key prefix;
    • the access key ID and secret access key;
    • an optional public endpoint if generated links must use a different hostname.
  4. Leave Force path-style addressing enabled for most S3-compatible services. AWS S3 commonly supports either style.
  5. Choose Test connection. Stairway verifies that the credentials can access the bucket.
  6. Choose Save profile.

The secret is encrypted before it is stored. Stairway never shows it again. When editing a profile, leave New secret blank to retain the stored value.

If a test fails, verify that the endpoint includes http:// or https://, the region matches the bucket, and the credentials allow HeadBucket, object listing, upload, and download operations.

Use a profile for a session​

  1. Open New browser session (/browsers/new).
  2. Under Artifact storage, choose Platform storage or one of your saved profiles.
  3. Start the session.

The choice applies only to that session. Stairway does not migrate artifacts from existing sessions or copy an artifact to both platform storage and your bucket.

Objects use this layout:

{optional-prefix}/downloads/{session-id}/...
{optional-prefix}/har/{session-id}/...
{optional-prefix}/session-states/{session-id}/...

Downloads remain available through Stairway's Downloads page. The web app relays access through the Stairway API, so it does not expose your S3 secret to the browser container or browser.

Share a profile​

Profile owners can choose Share and grant a team permission to use a profile. Team members can select the profile for sessions, test it, and access their authorized session artifacts. They cannot read its secret, edit it, or delete it.

Deleting a profile can stop artifact sync for sessions that still reference it. Keep a profile until those sessions no longer need to upload or retrieve artifacts.

What stays on Stairway storage​

Custom profiles contain only browser-session artifacts:

  • downloads;
  • HAR captures;
  • session-state snapshots.

Bug-report attachments, system-message attachments, and administrative diagnostics stay on Stairway's platform storage.

Operator configuration​

BYO storage requires share mode. Browser containers write artifacts to per-session host directories and stairway-worker uploads them with the resolved profile. Do not inject profile credentials into browser containers.

Configure both the API and worker with the same Fernet key:

STAIRWAY_CRED_ENC_KEY=<same-fernet-key-on-api-and-worker>

Generate a key once with:

python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

The worker also needs its browser-share root (STAIRWAY_SHARE_DIR), while the API needs STAIRWAY_BROWSER_SHARE_HOST_PATH. These paths must refer to the same host-side session tree.

By default, BYO endpoints that resolve to loopback, link-local, private, or reserved addresses are rejected to prevent server-side request forgery. Operators who intentionally use private VPC storage can allow only the required networks on both API and worker:

STAIRWAY_BYO_S3_ENDPOINT_ALLOW_CIDRS=10.20.0.0/16,fd00:1234::/48

Keep this allowlist narrow. Internal Stairway service names and metadata/link-local addresses remain unsuitable as user storage endpoints. If the worker cannot decrypt or reach a selected BYO profile, it leaves files for retry and does not silently upload them to platform storage.