TAG Quick Start

Get TAG running in under 5 minutes. TAG caches your Tigris objects on local disk so repeated reads are served in microseconds instead of milliseconds — and you don't need to change any application code.

Prerequisites

You need a pair of Tigris credentials (AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY) with read-only access to all buckets in your Tigris organization. These are TAG's service credentials. Your application clients authenticate separately with their own credentials.

Install and Run

Pick whichever method matches your environment.

Option A: Native Binary

# Download and install TAG
curl -sSL https://tag-releases.t3.storage.dev/install.sh | bash

# Set your Tigris credentials
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>

# Start TAG
tag

The install script auto-detects your OS (Linux/macOS) and architecture (amd64/arm64) and places the binary in /usr/local/bin.

Option B: Docker

Create a .env file with your credentials:

AWS_ACCESS_KEY_ID=<your-access-key>
AWS_SECRET_ACCESS_KEY=<your-secret-key>

Then start TAG:

cd docker/
docker compose up -d

The Docker image (tigrisdata/tag) uses Alpine Linux, runs as a non-root user, and persists cache data in a named volume.

Option C: Process Manager (run.sh)

For environments where you want simple process lifecycle management:

cd native/

# Set credentials
export AWS_ACCESS_KEY_ID=<your-access-key>
export AWS_SECRET_ACCESS_KEY=<your-secret-key>

# Start TAG (downloads binary if needed, waits for health check)
./run.sh start

# Check status
./run.sh status

# View logs
./run.sh logs 100

# Stop TAG
./run.sh stop

Use ./run.sh stop --clean to stop TAG and remove all cached data.

Verify It Works

TAG is now listening on http://localhost:8080. Try a few requests to make sure everything is connected:

# Health check
curl http://localhost:8080/health

# List buckets
aws s3 ls --endpoint-url http://localhost:8080

# Download an object
aws s3 cp s3://my-bucket/my-key ./local-file --endpoint-url http://localhost:8080

To confirm caching is working, request the same object twice. The first response comes from Tigris; the second comes from your local cache:

# First request - fetches from Tigris
curl -sI http://localhost:8080/my-bucket/my-key \
  -H "Authorization: ..." | grep X-Cache
# X-Cache: MISS

# Second request - served from local cache
curl -sI http://localhost:8080/my-bucket/my-key \
  -H "Authorization: ..." | grep X-Cache
# X-Cache: HIT

Connect Your Application

TAG works with any S3 client. Just change your endpoint URL to point at TAG and make sure path-style addressing is enabled — that's it.

Path-Style Addressing Only

TAG supports path-style addressing (http://host:port/bucket/key). Virtual-hosted style (http://bucket.host:port/key) is not supported. Ensure your S3 client is configured for path-style access.

For client examples covering AWS CLI, Python boto3, streaming large files, and troubleshooting, see S3 Client Usage.

Common Configuration

A few environment variables you may want to set right away:

Variable	Default	Description
TAG_LOG_LEVEL	info	Set to debug for verbose request logging
TAG_CACHE_DISK_PATH	/var/cache/tag	Where TAG stores cached objects
TAG_UPSTREAM_ENDPOINT	https://t3.storage.dev	Tigris S3 endpoint

For the full configuration reference, production deployment, clustering, TLS, and monitoring, see the Deployment Guide.

Troubleshooting

If something isn't working — TAG won't start, you're getting 403s, or every response shows X-Cache: MISS — see Troubleshooting in the Deployment Guide.