Object storage

Connect an S3-compatible bucket for templates across hosts, volumes, snapshots and backups.

Object storage lets every sandbox host share templates and keep sandbox data off any one machine. Any S3-compatible store works, and the control plane can run one for you.

Know what needs it

Feature	Without object storage
More than one sandbox host	A template exists only on the host that built it, so its sandboxes all land there.
Volumes	Unavailable. They are also off by default: see Turn on volumes.
Snapshot and template offload	Stays on the host's local disk.
Backups and cross-host restore	Unavailable.

Use the bundled store

setup.sh runs a SeaweedFS store by default (the s3 profile) and generates its keys. It is published on PT_PRIVATE_IP:9000, where the control plane and every host reach it.

Create the bucket once, after the first start:

# on the control plane, in platinum/infra/compose
docker compose exec s3 sh -c 'echo "s3.bucket.create -name platinum" | weed shell'

The bundled store speaks plain HTTP. Keep PT_PRIVATE_IP on a private network, or allow only your hosts to reach :9000.

Bring your own store

Run setup.sh with --no-s3, then set the store in .env.

# in platinum/infra/compose/.env
PT_S3_ENDPOINT=https://s3.example.com
PT_S3_REGION=us-east-1
PT_S3_BUCKET=platinum
PT_S3_ACCESS_KEY=…
PT_S3_SECRET_KEY=…
PT_S3_PREFIX=                 # optional key prefix

PT_S3_ENDPOINT takes host[:port], which means HTTPS, or a full http(s)://host[:port] URL. Apply it with docker compose up -d. The endpoint must be reachable from the control plane and from every host.

Give each host the same values

The installer copies the PT_S3_* values into each host's /etc/platinum/host.env when it runs. A host enrolled before you set up storage needs them added by hand:

# on the sandbox host, append the same PT_S3_* lines to /etc/platinum/host.env, then
sudo systemctl restart platinum-host-agent

With the bundled store, the endpoint for hosts is http://<PT_PRIVATE_IP>:9000.

Check a host

sudo journalctl -u platinum-host-agent -b | grep 'host-agent\] s3:'

Line	Meaning
`s3: enabled bucket=…`	Working
`s3: DEGRADED … CANNOT READ: <error>`	Keys are set, but the store refused them or is unreachable
`s3: disabled`	`PT_S3_ENDPOINT`, `PT_S3_BUCKET` or `PT_S3_ACCESS_KEY` is missing from `host.env`

Turn on volumes

Volumes are off by default. With object storage working, turn them on with the admin token:

for k in flags.volumes_enabled flags.vol_v1_enabled; do
  curl -s -X PUT "https://api.example.com/internal/admin/config/$k" \
    -H "Authorization: Bearer $ADMIN_TOKEN" -H 'content-type: application/json' -d '{"value":true}'
done

The change is live with no restart. See Volumes for using them.

Keep the bucket safe

The control plane removes unreferenced chunks itself, nightly (PT_CAS_GC_IN_PROCESS=1).
Never change PT_S3_BUCKET or PT_S3_PREFIX on a running install. Keep them identical on the control plane and every host.
Use a key limited to this one bucket.
Back the bucket up with your store's own tools, or any S3 sync tool. See Backups.