From Source

This guide covers how to install and run Sesame directly on your system. For containerized deployments, see the Docker guide.

Requirements

Runtime: Bun v1.0 or later
Git: For cloning repositories into task sandboxes
Storage: SQLite database (file-based, no external DB needed)

Quick Start

1. Clone and Install

git clone https://github.com/jakejarvis/sesame.git
cd sesame
bun install

2. Configure Environment

Copy the example environment file:

cp .env.example .env

Generate the required secrets:

# Generate BETTER_AUTH_SECRET
openssl rand -base64 32

# Generate ENCRYPTION_KEY
openssl rand -hex 32

Update your .env file with the generated values:

.env

# Required
BETTER_AUTH_SECRET=your-generated-secret
BASE_URL=http://localhost:13531
ENCRYPTION_KEY=your-encryption-key

# Optional: Customize app name
VITE_APP_NAME=Sesame

See Configuration for all available settings and Authentication for SSO setup.

3. Start the Server

Development mode (with hot reload):

bun run dev

This starts both the backend and frontend in development mode:

Frontend: http://localhost:13530 (Vite dev server with HMR)
Backend: http://localhost:13531 (Hono API server)

The Vite dev server automatically proxies /api requests to the backend.

Production mode:

# Build the frontend
bun run build

# Start the server (serves both API and static files)
bun run start

When built, the Hono server serves both the API and static frontend files from port 13531.

4. Create Admin Account

The first user to sign up automatically becomes an admin. Navigate to the app and create your account.

Monorepo Commands

Sesame uses Turborepo for build orchestration:

# Development (all apps)
bun run dev

# Development (specific app)
bun run dev --filter=@sesame/server    # Backend only
bun run dev --filter=@sesame/web       # Frontend only

# Build all apps
bun run build

# Type checking
bun run check-types

# Linting
bun run lint

# Format code
bun run format

Database Commands

# Generate migrations from schema changes
bun run db:generate

# Run pending migrations
bun run db:migrate

# Push schema directly (dev only)
bun run db:push

# Open Drizzle Studio GUI
bun run db:studio

Project Structure

server

web

shared

sandbox

agents

data

turbo.json

Updating

git pull
bun install
bun run build
# Restart the server

Database migrations run automatically on startup.

Running Individual Apps

If you need to run apps separately:

Backend only:

cd apps/server
bun run dev
# Runs on http://localhost:13531

Frontend only:

cd apps/web
bun run dev
# Runs on http://localhost:13530 (proxies /api to :13531)

Environment Variables

The monorepo shares environment variables from the root .env file. Key variables:

Variable	Description	Default
`PORT`	Backend server port	`13531`
`HOST`	Backend server host	`localhost`
`DATABASE_PATH`	SQLite database path	`./data/sesame.db`
`BETTER_AUTH_SECRET`	Auth encryption secret	(required)
`BASE_URL`	Public URL	`http://localhost:13531`
`ENCRYPTION_KEY`	Data encryption key	(required)

Next Steps

Configure authentication - Set up SSO/OIDC
Add agent credentials - Use your AI subscriptions
Connect GitHub - Set up repository access

On this page