Storage & S3 Gateway

Credentials and endpoint

Create or rotate S3 credentials from the Storage console. The S3 endpoint is https://s3.walos.xyz, and the direct REST routes use x-walos-api-key. Secrets are shown once on create or rotate.

export AWS_ACCESS_KEY_ID=walos_...
export AWS_SECRET_ACCESS_KEY=...
aws --endpoint-url https://s3.walos.xyz s3api put-object --bucket assets --key hero.png --body ./hero.png
aws --endpoint-url https://s3.walos.xyz s3api get-object --bucket assets --key hero.png ./hero.png

SDK quickstart

Use @walos/sdk from server-side code so the Walos API key stays in WALOS_API_KEY. The client wraps bucket create/list, object upload/read/list/delete, namespace usage, and server-generated browser upload URLs.

import { WalosClient } from '@walos/sdk';

const client = new WalosClient({
  baseUrl: 'https://walos.xyz',
  apiKey: process.env.WALOS_API_KEY!
});

const bucket = await client.storage.createBucket({
  name: 'Assets',
  slug: 'assets'
});
const buckets = await client.storage.listBuckets();

await client.storage.uploadObject({
  namespace: 'assets',
  key: 'hero.png',
  body: await Bun.file('./hero.png').arrayBuffer(),
  contentType: 'image/png',
  epochs: 5
});

const uploadUrl = await client.storage.createUploadUrl({
  namespace: 'assets',
  key: 'browser/hero.png',
  contentType: 'image/png',
  contentLength: 1024
});
const object = await client.storage.readObject({ namespace: 'assets', key: 'hero.png' });
const bucketId = typeof bucket.id === 'string' ? bucket.id : 'assets';
const objects = await client.storage.listObjects({ bucketId, prefix: '', limit: 20 });
const usage = await client.storage.getUsage({ namespace: 'assets' });
await client.storage.deleteObject({ namespace: 'assets', key: 'hero.png' });
console.log(bucket, buckets, uploadUrl, object, objects, usage);

Direct storage routes

• /v1/storage/objects/[key]: upload or read an object with ?namespace=[bucket].
• /v1/storage/namespaces/[namespace]/usage: read byte-epoch quota state and failed upload counts.
• /api/storage/cdn/[blob_id]: public CDN read path returned by upload responses.

curl -X PUT 'https://walos.xyz/v1/storage/objects/hero.png?namespace=assets'   -H 'x-walos-api-key: wak_...'   -H 'content-type: image/png'   --data-binary @hero.png
curl 'https://walos.xyz/v1/storage/namespaces/assets/usage'   -H 'x-walos-api-key: wak_...'

Console bucket actions

Bucket rows in the Storage console copy route-backed values only: the upload API path, namespace usage path, and s3://bucket URI. Bucket deletion, pause, and rename controls are not shown until matching server actions exist.