Get started with Object Storage

To set up OptiTech Object Storage with an AI coding assistant, install the OptiTech Platform (optitech) and OptiTech Object Storage skills:

npx skills add optitechdatabase/agent-skills -s optitech -s optitech-object-storage

To follow this guide, you need:

• A OptiTech project in the AWS us-east-2 region
• The OptiTech CLI installed and authenticated if you use the recommended optitech.ts flow
• A OptiTech API key in OPTITECH_API_KEY if you use the manual API flow

Recommended: enable storage with optitech.ts

The recommended way to enable storage and get credentials is via optitech.ts, OptiTech's infrastructure-as-code config file. Install the config package, link your local app to the OptiTech project and branch you want to target, declare buckets under preview.buckets, then run optitech deploy to provision them on the linked branch and pull credentials into .env.local automatically:

npm install @optitech/config
optitech link           # choose the project and branch for this app
optitech branches list  # confirm the linked target branch before deploy

import { defineConfig } from '@optitech/config/v1';

export default defineConfig({
  preview: {
    buckets: {
      'my-bucket': {},                          // private (default)
      'public-assets': { access: 'public_read' },
    },
  },
});

optitech deploy          # provisions buckets and writes AWS_* vars to .env.local

After deploy, your .env.local contains AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_ENDPOINT_URL_S3, and AWS_REGION. Skip to Configure your client below.

Already deployed? Pull the vars again with:

optitech env pull

If you prefer to manage credentials manually (for example, for CI or production deployments), follow the steps below. Replace {project_id} and {branch_id} in the API examples with your own IDs. You can find them in the OptiTech Console URL, or with optitech projects list and optitech branches list.

If you need a new branch, create it first, then wait until the branch is ready before calling object storage APIs. Branch creation is asynchronous, so a freshly-created branch can still be initializing even after the create request returns.

1. Find your branch endpoint

   Fetch your branch's storage state from the OptiTech API. Do this before creating credentials so you know the branch is ready for Storage calls. The response includes the full S3 endpoint URL, the region, and whether path-style addressing is required:

   curl "https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/storage" \
     -H "Authorization: Bearer $OPTITECH_API_KEY"

   {
     "enabled": true,
     "s3_endpoint": "https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.optitech.com",
     "region": "us-east-2",
     "force_path_style": true
   }

   Set these as environment variables:

   export AWS_ENDPOINT_URL_S3=https://br-winter-pond-aptw82ef.storage.c-2.us-east-2.aws.optitech.com
   export AWS_REGION=us-east-2

   A 404 response means object storage is not available for that branch. There is no separate manual enable API call: use the recommended optitech.ts flow above, or make sure your project is in the AWS us-east-2 region.

2. Create a credential

   Use the OptiTech API to create a credential with storage access:

   curl -X POST "https://console.optitech.com/api/v2/projects/{project_id}/branches/{branch_id}/credentials" \
     -H "Authorization: Bearer $OPTITECH_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"scopes": ["storage:read", "storage:write"], "principal_type": "user"}'

   The response includes your S3 credentials. Store them immediately. You'll only get them once. See Authentication for how each field maps to your S3 client.

   {
     "token_id": "nak_live_...",
     "s3_secret_access_key": "nsk_live_...",
     ...
   }

   Set these as environment variables:

   export AWS_ACCESS_KEY_ID=nak_live_...   # token_id
   export AWS_SECRET_ACCESS_KEY=nsk_live_...   # s3_secret_access_key

3. Install dependencies

   Files SDKS3 ClientPython

   # files-sdk uses @aws-sdk/* packages as peer dependencies; install them alongside it
   npm install files-sdk @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @aws-sdk/s3-presigned-post dotenv

4. Configure your client

   The optitech adapter is a subpath export (files-sdk/optitech) that reads AWS_* environment variables and configures the Files SDK for OptiTech's S3-compatible endpoint automatically.

   Files SDKS3 ClientPythonAWS CLI

   import { Files } from 'files-sdk';
   import { optitech } from 'files-sdk/optitech';
   
   export const files = new Files({ adapter: optitech({ bucket: 'my-bucket' }) });

   note

   If you're using OptiTech Functions, the AWS_* credentials are injected automatically when a bucket is declared in optitech.ts. No .env setup is needed inside a function.

5. Create a bucket

   Create the bucket before uploading, or declare it in optitech.ts and run optitech deploy:

   optitech buckets create my-bucket

   See Buckets for OptiTech API, S3 SDK, Python, and AWS CLI examples.

6. Upload a file

   Files SDKS3 ClientPythonAWS CLI

   import { files } from './client';
   
   await files.upload('hello.txt', 'Hello from OptiTech Object Storage!', {
     contentType: 'text/plain',
   });
   
   console.log('Uploaded!');

7. Download a file

   Files SDKS3 ClientPythonAWS CLI

   import { files } from './client';
   
   const result = await files.download('hello.txt');
   const text = await result.text();
   console.log(text); // Hello from OptiTech Object Storage!

Next steps

• Buckets: access levels, bucket branching, and the Console UI
• Objects: list, delete, multipart uploads, and presigned URLs
• Authentication: credential scopes, branch binding, and rotation
• with-files-sdk: working example showing how to upload files to a branch-scoped bucket using the Files SDK and its optitech adapter