Settings

Settings can be configured in three ways, in order of priority:

1. Environment variables - Highest priority, locks the setting (can't change via UI)
2. Config file - Editable via admin UI, supports multiple formats
3. Built-in defaults - Used when nothing else is set

Config File

Create a config.json (or config.yaml, config.jsonc, config.toml) in the project root:

{
  "ai": {
    "baseUrl": "https://api.openai.com/v1",
    "apiKey": "sk-...",
    "model": "gpt-4o-mini"
  },
  "registration": {
    "allowNewUsers": true,
    "requireEmailVerification": false
  },
  "tasks": {
    "baseDirectory": "/tmp/sesame"
  },
  "git": {
    "includeCoAuthoredBy": true
  },
  "gravatar": {
    "enabled": true
  },
  "oidc": {
    "enabled": true,
    "providerId": "authentik",
    "providerName": "Authentik",
    "clientId": "your-client-id",
    "clientSecret": "your-client-secret",
    "issuer": "https://auth.example.com/application/o/sesame"
  },
  "smtp": {
    "host": "smtp.gmail.com",
    "port": 587,
    "secure": false,
    "user": "your-email@gmail.com",
    "pass": "your-app-password",
    "from": "Sesame <noreply@yourdomain.com>"
  }
}

The admin panel at /admin/settings provides a UI for editing these values.

Environment Variable Locking

When you set a value via environment variable, it:

• Takes precedence over the config file
• Appears as "locked" in the admin UI
• Cannot be changed without restarting with a different env var

This is useful for Docker deployments where you want to enforce certain settings.

Required Environment Variables

AI Provider Configuration (Utility Tasks)

This configures the AI model used for utility tasks only: generating branch names, commit messages, and task titles. It does not run the coding agents themselves—each agent uses its own authentication.

Any OpenAI-compatible API works (OpenAI, Anthropic, Ollama, vLLM, Together, etc.)

Provider Examples

OpenAI:

AI_API_KEY=sk-...
AI_BASE_URL=https://api.openai.com/v1
AI_MODEL=gpt-4o-mini

Anthropic:

AI_API_KEY=sk-ant-...
AI_BASE_URL=https://api.anthropic.com/v1
AI_MODEL=claude-3-haiku-20240307

Ollama (local):

AI_BASE_URL=http://localhost:11434/v1
AI_MODEL=llama3
# No API key needed for local Ollama

SSO / OIDC Configuration

See Authentication & SSO for detailed setup instructions.

Sandbox Provider

Sesame supports multiple sandbox providers for running agent tasks. See the dedicated documentation for each provider:

• Filesystem Sandbox - Default, runs tasks in temp directories
• Docker Sandbox - Runs tasks in isolated containers

User Registration

SMTP Configuration

SMTP is required for email verification and password reset functionality. Any standard SMTP server works (Gmail, SendGrid, AWS SES, Mailgun, Postmark, etc.)

Provider Examples

Gmail (App Password):

SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_SECURE=false
SMTP_USER=your-email@gmail.com
SMTP_PASS=your-app-password
SMTP_FROM="Sesame <your-email@gmail.com>"

SendGrid:

SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USER=apikey
SMTP_PASS=SG.your-api-key
SMTP_FROM="Sesame <noreply@yourdomain.com>"

AWS SES:

SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USER=your-ses-smtp-user
SMTP_PASS=your-ses-smtp-password
SMTP_FROM="Sesame <noreply@yourdomain.com>"

Mailgun:

SMTP_HOST=smtp.mailgun.org
SMTP_PORT=587
SMTP_USER=postmaster@yourdomain.com
SMTP_PASS=your-mailgun-password
SMTP_FROM="Sesame <noreply@yourdomain.com>"

Agent API Keys

These system-wide keys are used when users don't have their own credentials configured:

Sandbox Security

Sesame can use OS-level sandboxing via @anthropic-ai/sandbox-runtime to restrict agent filesystem and network access. This provides defense-in-depth beyond process isolation.

Admin Configuration

The admin panel at /admin/sandbox allows configuring:

• Default Enabled: Whether sandbox security is on by default for new tasks
• Global Allowed Domains: Network domains all tasks can access (in addition to agent-specific domains)
• Global Denied Domains: Network domains blocked for all tasks

Per-Task Configuration

When creating a task, users can toggle sandbox security on/off (if the admin default allows it). The task detail view shows:

• Whether sandbox security was enabled
• Any violations detected during execution

Agent Domain Allowlists

Each agent has built-in domain allowlists for their required APIs.

Security Properties

When sandbox security is enabled:

• Filesystem: Write access limited to project directory and /tmp. Sensitive paths like ~/.ssh, ~/.aws are blocked.
• Network: Only allowed domains can be accessed. Violations are logged and streamed to the UI.
• Monitoring: Real-time violation detection via Server-Sent Events.

Audit Logging

Sesame maintains comprehensive audit logs tracking user activity, authentication events, credential changes, task lifecycle, and administrative actions.

What Gets Logged

Authentication Events:

• User login/logout (via better-auth session hooks)
• New user registration
• Session creation and expiration

Credential Changes:

• API key created, updated, or deleted
• Agent credentials created, updated, or deleted
• OpenCode provider connected or disconnected

Task Lifecycle:

• Task created, started, completed, failed, stopped, or deleted

Admin Actions:

• Settings changed (logs which keys changed, not values)
• User role changed
• User banned/unbanned
• User deleted

Viewing Audit Logs

Access audit logs in the admin panel at /admin/audit. The interface provides:

• Filters: Filter by action type, resource type, or user ID
• Live Tail: Auto-refresh every 5 seconds to monitor activity in real-time
• Export: Download filtered logs as CSV or JSON
• Detail View: Click any row to see full payload, user agent, and timestamps
• Virtualized Table: Smooth scrolling even with large datasets

Data Retention

Audit logs are automatically cleaned up based on retentionDays. The cleanup runs probabilistically (~1% of writes) to avoid performance overhead. Set retentionDays to 0 to retain logs indefinitely.

Export API

Export filtered audit logs programmatically:

# Export as JSON
curl -H "Cookie: ..." "https://your-instance/api/admin/audit/export?format=json"

# Export as CSV with filters
curl -H "Cookie: ..." "https://your-instance/api/admin/audit/export?format=csv&action=user_login&startDate=2024-01-01"

Supported query parameters: format (csv/json), action, resourceType, userId, startDate, endDate.

Git Configuration

Configure how commits are made by agents.

Commit Attribution

When a user has connected their GitHub PAT, commits are attributed to their GitHub identity using the noreply email format (username@users.noreply.github.com). If no PAT is connected, commits are attributed to "Sesame Agent" (agent@sesame.works).

Co-authored-by Trailer

By default, all commits include a trailer indicating AI assistance:

Fix memory leak in parser

Co-authored-by: Sesame <agent@sesame.works>

To disable this, set GIT_INCLUDE_CO_AUTHORED_BY=false or toggle it off in the admin settings.

User Avatars

Sesame can display user avatars from Gravatar based on their email address.

When enabled, users without a custom avatar will have their Gravatar displayed (if they have one associated with their email). If no Gravatar exists, a fallback initial is shown.

Admin Panel

Access the admin panel at /admin to:

• Manage users and permissions
• Configure SSO/OIDC settings
• Adjust application settings
• View system health and status
• Browse and export audit logs with filtering and live tail