> ## Documentation Index
> Fetch the complete documentation index at: https://docs.neurometric.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Local Setup

> How to run the Inference Studio locally for development.

# 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:

```bash theme={null}
# 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](http://localhost:3000).

### Services:

* **App:** Running at [http://localhost:3000](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](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:

```bash theme={null}
# 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:

```bash theme={null}
# 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.

<Warning>
  **CRITICAL:** Keep this key secret! Rotating this key will invalidate all encrypted API keys in the database.
</Warning>

**Generate a new key:**

```bash theme={null}
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.