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 Settings dialog, 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-5-nano"
  },
  "sessions": {
    "baseDirectory": "/tmp/sesame"
  },
  "git": {
    "includeCoAuthoredBy": true
  },
  "sesameApi": {
    "baseUrl": "https://api.sesame.works"
  }
}

The Settings dialog (gear icon → General) 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 Settings dialog
• 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 operations only: generating branch names, commit messages, and session 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-5-nano

Anthropic:

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

OpenRouter:

AI_API_KEY=sk-or-v1-...
AI_BASE_URL=https://openrouter.ai/api/v1
AI_MODEL=google/gemini-2.5-flash-lite

Ollama (local):

AI_BASE_URL=http://localhost:11434/v1
AI_MODEL=llama3

Sesame API

The Sesame public API provides centralized model listings and version checks. The server proxies requests to this API so the frontend doesn't need direct access.

Self-hosters can point this to their own instance of the Sesame API. Setting SESAME_API_URL via environment variable locks the value.

Authentication

By default, no authentication is required — all endpoints are open. Set AUTH_PASSWORD to protect your instance with HTTP Basic Auth.

Sandbox Provider

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

• Filesystem Sandbox - Default, runs sessions in temp directories
• Docker Sandbox - Runs sessions in isolated containers
• Vercel Sandbox - Ephemeral cloud microVMs
• Daytona Sandbox - Cloud development sandboxes
• E2B Sandbox - Lightweight cloud VMs (~150ms boot)

Agent Credentials

Sesame manages all agent authentication through a unified Agent Credentials dialog (Settings → Credentials, or click the key icon on an unconfigured agent in the session form). Each agent is shown as an expandable accordion item with its icon, name, and connection status.

Authentication Methods

Agents that support both methods show two tabs: Subscription (first) and API Key. Agents with only one method (Copilot: subscription only, Gemini and Amp: API key only) show the form directly without tabs.

For Claude Code and Codex, the Subscription tab offers two ways to authenticate:

1. Sign in directly — Click "Sign in with..." to start a browser-based OAuth flow without leaving Sesame
2. Enter a token manually — Paste a token below the "or enter token manually" divider (useful if you already have one from running the CLI locally)

System-Wide API Keys

These keys are used as fallbacks when no credentials are configured in the UI:

Credential Priority

When running a session, Sesame checks for credentials in order:

1. Subscription Credentials (Agent Credentials → Subscription tab)
2. API Keys (Agent Credentials → API Key tab)
3. System API Keys (environment variables)

If no credentials are found, the session form shows an "Authenticate..." button instead of the model dropdown. Clicking it opens the Agent Credentials dialog for that agent.

Credential Security

• Encryption: All credentials are encrypted at rest using AES-256-GCM via the ENCRYPTION_KEY environment variable. Credentials are only decrypted when executing a session.
• Revocation: Remove credentials in Sesame via Agent Credentials → Remove, then revoke the token in your provider's settings.

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.

Configuration

The Settings dialog (gear icon → Sandbox) allows configuring:

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

Per-Session Configuration

When creating a session, sandbox security can be toggled on/off. The session 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.

Git Configuration

Configure how commits are made by agents.

Commit Attribution

When a GitHub PAT is connected, commits are attributed to the associated 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 Settings → General.