S3 Vectors Workbench

S3 Vectors Workbench is a local UI and TypeScript SDK for building with Amazon S3 Vectors and Amazon Bedrock embeddings.

It removes the setup grind from vector workflows: connect AWS credentials, create buckets and indexes, generate embeddings, insert vectors, and test similarity search from one developer-friendly workbench.

Features

• Connect with local AWS profiles, the default provider chain, or session-only access keys.
• Discover local AWS profiles from ~/.aws/config and ~/.aws/credentials.
• Manage S3 vector buckets.
• Manage S3 vector indexes.
• List, insert, update, delete, and query vectors.
• Generate text and image embeddings through Amazon Bedrock.
• Use text, image URLs, base64 strings, or data URLs for embedding input.
• Run metadata-aware similarity queries.
• Keep AWS secrets out of browser local storage and logs.
• Use the SDK directly from Node.js applications.

Quick Start

Run the workbench without installing it globally:

npx s3-vectors-workbench

Or install it globally:

npm install -g s3-vectors-workbench
s3-vectors-workbench

CLI Usage

s3-vectors-workbench

By default, the API server listens on port 4317.

PORT=5000 s3-vectors-workbench

Authentication Modes

The workbench supports three AWS authentication modes:

type AwsAuthMode = "profile" | "access-key" | "default-provider-chain";

Local AWS Profile

Reads profiles from:

• ~/.aws/config
• ~/.aws/credentials

The browser stores only non-secret profile metadata. AWS credentials remain on the backend side.

Default Provider Chain

Uses the standard AWS SDK default provider chain, including environment variables, SSO/session configuration, instance roles, container roles, and other supported sources.

Session Access Key

Access keys are held in server memory for the active session only.

They are not persisted to browser local storage.

Required AWS Permissions

Exact permissions depend on which features you use. A development policy may include:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3vectors:ListVectorBuckets",
        "s3vectors:CreateVectorBucket",
        "s3vectors:GetVectorBucket",
        "s3vectors:DeleteVectorBucket",
        "s3vectors:GetVectorBucketPolicy",
        "s3vectors:PutVectorBucketPolicy",
        "s3vectors:DeleteVectorBucketPolicy",
        "s3vectors:ListIndexes",
        "s3vectors:CreateIndex",
        "s3vectors:GetIndex",
        "s3vectors:DeleteIndex",
        "s3vectors:ListVectors",
        "s3vectors:GetVectors",
        "s3vectors:PutVectors",
        "s3vectors:DeleteVectors",
        "s3vectors:QueryVectors",
        "s3vectors:TagResource",
        "s3vectors:UntagResource",
        "s3vectors:ListTagsForResource"
      ],
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": [
        "bedrock:InvokeModel"
      ],
      "Resource": "*"
    }
  ]
}

For production use, scope resources and regions as tightly as possible.

SDK Usage

import { S3VectorsWorkbench } from "s3-vectors-workbench/sdk";

const toolkit = new S3VectorsWorkbench({
  region: "us-east-1",
  auth: {
    mode: "profile",
    profileName: "default"
  }
});

const embedding = await toolkit.bedrock.embedText({
  modelId: "amazon.titan-embed-text-v2:0",
  text: "wireless headphones",
  inputType: "search_query"
});

const results = await toolkit.s3vectors.query({
  bucketName: "product-embeddings",
  indexName: "product-index",
  vector: embedding.vector,
  topK: 10,
  returnMetadata: true
});

Image Embeddings

const embedding = await toolkit.bedrock.embedImage({
  modelId: "amazon.titan-embed-image-v1",
  image: {
    source: "url",
    value: "https://example.com/product.jpg"
  },
  text: "optional context"
});

Supported image input sources:

• url
• base64
• data-url

Server Usage

import { createWorkbenchServer } from "s3-vectors-workbench/server";

const app = createWorkbenchServer({
  logLevel: "info"
});

app.listen(4317, () => {
  console.log("S3 Vectors Workbench API listening on http://127.0.0.1:4317");
});

Package Exports

import { S3VectorsWorkbench } from "s3-vectors-workbench/sdk";
import { createWorkbenchServer } from "s3-vectors-workbench/server";

Security Notes

S3 Vectors Workbench is designed as a local developer tool.

• AWS secrets are not logged.
• Access-key credentials are session-only.
• Browser local storage is used only for non-secret UI/profile metadata.
• The browser never calls AWS services directly.
• Do not expose this app as a shared multi-user service without adding authentication, authorization, CSRF protection, and a proper external secret store.

License

MIT License. See LICENSE.