Setup Guide

There are several ways to run the Inference Studio locally, depending on your workflow.

Using Docker Compose (Recommended)

The easiest way to get started is using Docker Compose, which sets up the Next.js application, PostgreSQL database, and LocalStack for an S3 simulation:

# Start all services (app + PostgreSQL + LocalStack)
docker compose up

# In another terminal, seed the database (first time only)
docker compose exec app npm run db:seed

The application will be available at http://localhost:3000.

Services:

App: Running at http://localhost:3000 (Environment variable AWS_S3_EXPERIMENT_BUCKET is automatically set to local-bucket)
PostgreSQL: At localhost:5432 with user postgres / password postgres
LocalStack (S3): Available at http://localhost:4566
- AWS Access Key ID: test
- AWS Secret Access Key: test
- Default region: us-east-1
- S3 bucket data persists in ./s3-bucket/ directory
- Default bucket local-bucket is automatically created on startup

Interacting with LocalStack S3 Bucket:

You can interact with the LocalStack S3 bucket using AWS CLI commands via Docker:

# List all buckets
docker compose exec localstack awslocal s3 ls

# List contents of the bucket
docker compose exec localstack awslocal s3 ls s3://local-bucket

# Show file content from the bucket
docker compose exec localstack awslocal s3 cp s3://local-bucket/your-file.json -

Note: When running everything in Docker Compose, the DATABASE_URL uses db as the hostname. The connection string is automatically set to: postgresql://postgres:postgres@db:5432/studio_development

Hybrid Setup (Database in Docker, App Locally)

You can run the database in Docker while running the application locally for faster development:

# Start only the database service
docker compose up -d db

# In another terminal, set up and run the app locally
cd inference-studio
npm install

# Create a .env file with DATABASE_URL using localhost (not 'db')
# Example: DATABASE_URL=postgresql://postgres:postgres@localhost:5432/postgres

# Create prisma client, schema, and populate with sample data
npm run db:generate
npm run db:push
npm run db:seed

# Start development server
npm run dev

Security & Encryption (MASTER_KEY)

The application uses MASTER_KEY to encrypt sensitive API credentials (like Langfuse API keys) stored in the database.

CRITICAL: Keep this key secret! Rotating this key will invalidate all encrypted API keys in the database.

Generate a new key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Must be exactly 64 hexadecimal characters (256 bits).
Must be the same across all application and worker instances.
Set it as an environment variable (MASTER_KEY=your_64_character_hex_string_here).

The docker-compose.yml includes a default development key. For production, set MASTER_KEY in your environment before running.

Getting started

Inference Studio

SLM Marketplace

Local Setup

Setup Guide

Using Docker Compose (Recommended)

Services:

Interacting with LocalStack S3 Bucket:

Hybrid Setup (Database in Docker, App Locally)

Security & Encryption (MASTER_KEY)

​Setup Guide

​Using Docker Compose (Recommended)

​Services:

​Interacting with LocalStack S3 Bucket:

​Hybrid Setup (Database in Docker, App Locally)

​Security & Encryption (MASTER_KEY)

Setup Guide

Using Docker Compose (Recommended)

Services:

Interacting with LocalStack S3 Bucket:

Hybrid Setup (Database in Docker, App Locally)

Security & Encryption (MASTER_KEY)