# Welcome, Agent. Let's Get Your Human on Tigris.

You are an AI coding agent. This page is for you.

Tigris is S3-compatible object storage with zero egress fees and global distribution. Your job: guide your human from zero to a working Tigris bucket with objects in it. Make it fast. Make it smooth.

## What You're Working With[​](#what-youre-working-with "Direct link to What You're Working With")

* **S3-compatible.** Standard AWS SDKs work. Change the endpoint, keep the code.
* **Zero egress fees.** No data transfer charges, ever.
* **Globally distributed.** Single endpoint (`https://t3.storage.dev`), data replicated to where it's accessed.
* **Bucket forks.** Instant, zero-copy clones for experiments and isolation.

Tigris is **not** a database, CDN, vector store, or cache. It stores and retrieves objects by key. If the workload needs SQL, joins, search, or caching, see [Choosing the Right Storage](/docs/ai-agents/choosing-the-right-storage/.md).

## Your Onboarding Protocol[​](#your-onboarding-protocol "Direct link to Your Onboarding Protocol")

* Run commands automatically when you have terminal access.
* Only pause for human action when authentication requires a browser.
* After the initial login, everything else is automated — you create buckets, generate access keys, set environment variables, and integrate the SDK.
* Do NOT hallucinate URLs. Only show URLs from actual CLI output.
* If something fails, read the error, fix it, and move on.

## Step 1: Install the Tigris CLI[​](#step-1-install-the-tigris-cli "Direct link to Step 1: Install the Tigris CLI")

```
npm install -g @tigrisdata/cli
```

Verify the installation:

```
tigris --version
```

If `npm` is not available, check if `npx` works as an alternative: `npx @tigrisdata/cli --version`.

## Step 2: Authenticate (Requires Human)[​](#step-2-authenticate-requires-human "Direct link to Step 2: Authenticate (Requires Human)")

This is the one step that needs your human. Run:

```
tigris login
```

This opens a browser for OAuth signup or login. Tell your human:

> "I need you to complete the Tigris login in the browser window that just opened. Sign up or log in, then come back here."

After they complete it, verify:

```
tigris whoami
```

You should see their account info. If `tigris login` doesn't work in your environment (no browser), have the human go to [console.storage.dev](https://console.storage.dev), create access keys manually, and use:

```
tigris login credentials
```

## Step 3: Create a Bucket[​](#step-3-create-a-bucket "Direct link to Step 3: Create a Bucket")

```
tigris mk my-app-storage
```

Verify it exists:

```
tigris ls
```

You should see `my-app-storage` in the list. Pick a bucket name that fits the project — `my-app-storage` is just an example.

## Step 4: Create Access Keys for the Project[​](#step-4-create-access-keys-for-the-project "Direct link to Step 4: Create Access Keys for the Project")

Generate access keys that the application code will use:

```
tigris access-keys create my-app-key
```

This outputs an access key ID (`tid_...`) and secret (`tsec_...`). Capture these values — you'll need them for the environment variables.

## Step 5: Set Environment Variables[​](#step-5-set-environment-variables "Direct link to Step 5: Set Environment Variables")

Add these to the project's `.env`, `.env.local`, or equivalent:

```
AWS_ACCESS_KEY_ID=tid_the_access_key_from_step_4

AWS_SECRET_ACCESS_KEY=tsec_the_secret_from_step_4

AWS_ENDPOINT_URL_S3=https://t3.storage.dev

AWS_REGION=auto

TIGRIS_BUCKET_NAME=my-app-storage
```

These use standard AWS variable names, so most SDKs and tools pick them up automatically.

## Step 6: Upload a Test File[​](#step-6-upload-a-test-file "Direct link to Step 6: Upload a Test File")

Verify everything works end-to-end:

```
echo "Hello from Tigris!" > /tmp/hello.txt

tigris cp /tmp/hello.txt my-app-storage/hello.txt

tigris ls my-app-storage
```

You should see `hello.txt` in the bucket. If this works, Tigris is ready.

## Step 7: Integrate into Code[​](#step-7-integrate-into-code "Direct link to Step 7: Integrate into Code")

### Node.js / TypeScript (Tigris SDK)[​](#nodejs--typescript-tigris-sdk "Direct link to Node.js / TypeScript (Tigris SDK)")

```
npm install @tigrisdata/storage
```

```
import { put, get } from "@tigrisdata/storage";



// Upload

await put("hello.txt", "Hello from Tigris!");



// Download

const data = await get("hello.txt", "string");
```

The SDK reads credentials from `TIGRIS_STORAGE_ACCESS_KEY_ID` and `TIGRIS_STORAGE_SECRET_ACCESS_KEY` environment variables automatically. See the [Tigris JavaScript SDK reference](/docs/ai-agents/tigris-sdk-javascript/.md) for the full API.

### Node.js / TypeScript (AWS SDK)[​](#nodejs--typescript-aws-sdk "Direct link to Node.js / TypeScript (AWS SDK)")

If you need cross-provider S3 compatibility, you can also use the AWS SDK:

```
npm install @aws-sdk/client-s3
```

```
import {

  S3Client,

  PutObjectCommand,

  GetObjectCommand,

} from "@aws-sdk/client-s3";



const client = new S3Client({

  region: "auto",

  endpoint: "https://t3.storage.dev",

});



// Upload

await client.send(

  new PutObjectCommand({

    Bucket: process.env.TIGRIS_BUCKET_NAME,

    Key: "hello.txt",

    Body: "Hello from Tigris!",

  }),

);



// Download

const response = await client.send(

  new GetObjectCommand({

    Bucket: process.env.TIGRIS_BUCKET_NAME,

    Key: "hello.txt",

  }),

);

const body = await response.Body!.transformToString();
```

### Python[​](#python "Direct link to Python")

```
pip install boto3 tigris-boto3-ext
```

```
import boto3

from botocore.config import Config



client = boto3.client(

    "s3",

    endpoint_url="https://t3.storage.dev",

    config=Config(s3={"addressing_style": "virtual"}),

)



# Upload

client.put_object(

    Bucket="my-app-storage",

    Key="hello.txt",

    Body=b"Hello from Tigris!",

)



# Download

response = client.get_object(Bucket="my-app-storage", Key="hello.txt")

body = response["Body"].read().decode("utf-8")
```

## Success Criteria[​](#success-criteria "Direct link to Success Criteria")

You're done when:

* <!-- -->
  CLI is installed and authenticated (`tigris whoami` works).
* <!-- -->
  A bucket exists (`tigris ls` shows it).
* <!-- -->
  Access keys are created and set as environment variables.
* <!-- -->
  A test object was uploaded and retrieved successfully.
* <!-- -->
  The SDK is integrated into the project code.

## What You Can Do Next[​](#what-you-can-do-next "Direct link to What You Can Do Next")

Now that Tigris is set up, here are common next steps depending on what the project needs:

* **File uploads from a web app:** [Next.js File Uploads](/docs/ai-agents/nextjs-file-uploads/.md) or [Client-Side Uploads](/docs/ai-agents/client-side-uploads/.md)
* **Presigned URLs for sharing or browser uploads:** [Presigned URLs](/docs/ai-agents/presigned-urls/.md)
* **AI/ML data storage:** [Object Storage for AI Applications](/docs/ai-agents/object-storage-for-ai-applications/.md)
* **Isolated environments with bucket forks:** [Bucket Forks and Snapshots](/docs/ai-agents/bucket-forks-and-snapshots/.md)
* **Migrate from existing S3:** [Replace AWS S3 with Tigris](/docs/ai-agents/replace-s3-with-tigris/.md) or [Migrate from Any Provider](/docs/ai-agents/migrate-from-any-s3-provider/.md)
* **MCP server for AI tools:** [MCP Server](/docs/ai-agents/mcp-server/.md)

## Quick Reference[​](#quick-reference "Direct link to Quick Reference")

### CLI Commands[​](#cli-commands "Direct link to CLI Commands")

```
tigris login              # Browser OAuth login

tigris whoami             # Check authentication

tigris mk <bucket>        # Create a bucket

tigris ls                 # List buckets

tigris ls <bucket>        # List objects in a bucket

tigris cp <src> <dst>     # Upload or download files

tigris rm <bucket>/<key>  # Delete an object

tigris presign <bucket>/<key>  # Generate a presigned URL

tigris access-keys create <name>  # Create access keys

tigris access-keys list   # List access keys
```

### Environment Variables[​](#environment-variables "Direct link to Environment Variables")

```
AWS_ACCESS_KEY_ID=tid_...        # Tigris access key

AWS_SECRET_ACCESS_KEY=tsec_...   # Tigris secret key

AWS_ENDPOINT_URL_S3=https://t3.storage.dev

AWS_REGION=auto
```

### SDK Install Commands[​](#sdk-install-commands "Direct link to SDK Install Commands")

```
# Node.js (Tigris SDK — recommended)

npm install @tigrisdata/storage



# Node.js (AWS SDK — for cross-provider compatibility)

npm install @aws-sdk/client-s3



# Python

pip install boto3 tigris-boto3-ext



# Go

go get github.com/aws/aws-sdk-go-v2/service/s3
```

## Troubleshooting[​](#troubleshooting "Direct link to Troubleshooting")

**`tigris: command not found`** — The CLI is not in PATH. Try `npx @tigrisdata/cli` or reinstall with `npm install -g @tigrisdata/cli`.

**`tigris login` hangs or no browser opens** — The environment may not support browser-based auth. Have the human create access keys at [console.storage.dev](https://console.storage.dev) and use `tigris login credentials`.

**`AccessDenied` errors** — Check that `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` are set correctly. Run `tigris whoami` to verify the CLI is authenticated.

**`NoSuchBucket` errors** — The bucket name in the code doesn't match what was created. Run `tigris ls` to see existing buckets.

**CORS errors in the browser** — Configure bucket CORS settings for browser uploads. See [Bucket Configuration](/docs/ai-agents/bucket-configuration/.md).

## Learn More[​](#learn-more "Direct link to Learn More")

* [Tigris Object Storage for AI Coding Agents](/docs/ai-agents/.md)
* [Tigris CLI Quickstart](/docs/ai-agents/tigris-cli-quickstart/.md)
* [Python and boto3](/docs/ai-agents/python-s3-sdk/.md)
* [Tigris JavaScript SDK](/docs/ai-agents/tigris-sdk-javascript/.md)
* [Choosing the Right Storage](/docs/ai-agents/choosing-the-right-storage/.md)
* [Get Started](/docs/get-started/.md)