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

# Environment Variables Reference

> Complete reference of all configuration environment variables

All bot configuration is done through environment variables in `.superturtle/.env` (created by `superturtle init`, gitignored). Never commit credentials.

## Required Variables

### TELEGRAM\_BOT\_TOKEN

Your Telegram bot token from @BotFather.

```bash theme={null}
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
```

Get this from [@BotFather](https://t.me/BotFather) with `/newbot`.

### TELEGRAM\_ALLOWED\_USERS

Comma-separated Telegram user IDs allowed to use the bot.

```bash theme={null}
# Single user
TELEGRAM_ALLOWED_USERS=123456789

# Multiple users
TELEGRAM_ALLOWED_USERS=123456789,987654321,555666777
```

Get your ID from [@userinfobot](https://t.me/userinfobot).

## Recommended Variables

### CLAUDE\_WORKING\_DIR

Default working directory for Claude. Claude can access files and run commands from here.

```bash theme={null}
CLAUDE_WORKING_DIR=~/my-assistant
```

`superturtle start` sets this automatically to the current project directory.

If you intentionally run the bot-folder launcher directly (`bun run start` or `bun run dev`), set `CLAUDE_WORKING_DIR` in your shell first so the launcher can find `CLAUDE_WORKING_DIR/.superturtle/.env`.

For repo development, prefer `node super_turtle/bin/superturtle.js start` from the repo root.

### OPENAI\_API\_KEY

API key for voice transcription (optional but required for voice messages).

```bash theme={null}
OPENAI_API_KEY=sk-proj-1234567890abcdef
```

Get from [platform.openai.com/api-keys](https://platform.openai.com/api-keys).

Voice transcription won't work without this, but other features are unaffected.

### SHOW\_TOOL\_STATUS

Show routine tool-call progress messages in Telegram while an answer runs.

```bash theme={null}
SHOW_TOOL_STATUS=false
```

Default: `false`. Keep this at `false` for quieter chats; set it to `true` only if you want the old per-tool progress updates back.

### MAIN\_PROVIDER

Startup default driver for the Telegram meta-agent.

```bash theme={null}
MAIN_PROVIDER=claude
```

Options:

* `claude`
* `codex`

Default: `claude`.

This is a startup default, not a forced override. Effective precedence is:

1. Saved last-used driver from Telegram
2. `MAIN_PROVIDER`
3. Built-in fallback `claude`

That means `/restart` keeps the user's last selected driver. If you set `MAIN_PROVIDER=codex`, you must also set `CODEX_ENABLED=true` and have a working local `codex` CLI; otherwise startup falls back to Claude.

## Codex

### CODEX\_ENABLED

Enable Codex driver and usage reporting.

```bash theme={null}
CODEX_ENABLED=true
```

Default: `false`. Requires a working local `codex` CLI login.

### META\_CODEX\_SANDBOX\_MODE

Sandbox restrictions for Codex SubTurtles.

```bash theme={null}
META_CODEX_SANDBOX_MODE=workspace-write
```

Options:

* `read-only` — Can only read files
* `workspace-write` — Can read/write workspace (default, recommended)
* `danger-full-access` — Full file system access (use cautiously)

### META\_CODEX\_APPROVAL\_POLICY

When to ask for approval before running Codex.

```bash theme={null}
META_CODEX_APPROVAL_POLICY=never
```

Options:

* `never` — Run without asking (default)
* `on-request` — Ask only when explicitly requested
* `on-failure` — Ask if something fails
* `untrusted` — Ask for untrusted tasks

### META\_CODEX\_NETWORK\_ACCESS

Allow Codex to make network requests.

```bash theme={null}
META_CODEX_NETWORK_ACCESS=false
```

Default: `false`. Set to `true` only if Codex needs to fetch URLs, call APIs, etc.

## File Access & Security

### ALLOWED\_PATHS

Comma-separated list of directories Claude can access.

```bash theme={null}
# Default (if not set):
ALLOWED_PATHS=$CLAUDE_WORKING_DIR,~/Documents,~/Downloads,~/Desktop,~/.claude

# Custom:
ALLOWED_PATHS=~/my-assistant,~/Documents/Notes,~/.claude
```

If you set this, it **overrides all defaults**. Make sure to include `~/.claude` if you use Claude Code plan mode.

### AUDIT\_LOG\_PATH

Path for security audit logs.

```bash theme={null}
AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
```

Default: `/tmp/claude-telegram-audit.log`. Set to empty string to disable logging.

### AUDIT\_LOG\_JSON

Log in JSON format (easier to parse programmatically).

```bash theme={null}
AUDIT_LOG_JSON=true
```

Default: `false`. Logs as text instead.

## Voice Transcription

### TRANSCRIPTION\_CONTEXT\_FILE

Path to a file with context for voice transcription.

```bash theme={null}
TRANSCRIPTION_CONTEXT_FILE=~/my-assistant/transcription-context.txt
```

Optional. If set, Claude will use this context when transcribing voice messages. Useful for including domain-specific words or acronyms.

Example file content:

```
This person discusses:
- Technologies: React, Node.js, TypeScript, Bun
- Companies: Anthropic, OpenAI, Typefully
- Personal interests: Sim racing, fitness, photography
```

## Dashboard (Optional)

### DASHBOARD\_ENABLED

Enable the bot's web dashboard.

```bash theme={null}
DASHBOARD_ENABLED=true
```

Default: `true`. Runs the local web dashboard unless explicitly disabled.

### DASHBOARD\_AUTH\_TOKEN

Authentication token for dashboard access.

```bash theme={null}
DASHBOARD_AUTH_TOKEN=your-secret-token
```

Optional. For local-only usage, leave unset. If set, dashboard requires this token (`Authorization: Bearer <token>`, `x-dashboard-token`, or `?token=`).

## Advanced Configuration

### CLAUDE\_CLI\_PATH

Path to the Claude CLI binary.

```bash theme={null}
CLAUDE_CLI_PATH=/opt/homebrew/bin/claude
```

Usually auto-detected. Set only if `claude` command is not in your PATH.

## Default Models & Effort

These values seed fresh driver preferences only. Once a user changes model, effort, or driver in Telegram, the saved preference wins over the env default.

### DEFAULT\_CLAUDE\_MODEL

Default Claude model for new users / empty preference files.

```bash theme={null}
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
```

Options:

* `claude-opus-4-6`
* `claude-sonnet-4-6`
* `claude-haiku-4-5-20251001`

Default: `claude-opus-4-6`

### DEFAULT\_CLAUDE\_EFFORT

Default Claude effort level for new users / empty preference files.

```bash theme={null}
DEFAULT_CLAUDE_EFFORT=medium
```

Options:

* `low`
* `medium`
* `high`

Default: `high`

### DEFAULT\_CODEX\_MODEL

Default Codex model for new users / empty preference files.

```bash theme={null}
DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
```

Options:

* `gpt-5.3-codex`
* `gpt-5.3-codex-spark`

Default: `gpt-5.3-codex`

### DEFAULT\_CODEX\_EFFORT

Default Codex reasoning effort for new users / empty preference files.

```bash theme={null}
DEFAULT_CODEX_EFFORT=low
```

Options:

* `minimal`
* `low`
* `medium`
* `high`
* `xhigh`

Default: `medium`

## Configuration Groups

### Minimal Setup

Bare minimum to run:

```bash theme={null}
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id
```

### Development Setup

Good for local testing:

```bash theme={null}
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id
CLAUDE_WORKING_DIR=~/my-dev-folder
SHOW_TOOL_STATUS=false
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
RATE_LIMIT_REQUESTS=100
OPENAI_API_KEY=your-key
```

### Personal Assistant Setup

Full-featured personal use:

```bash theme={null}
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id
CLAUDE_WORKING_DIR=~/my-assistant
SHOW_TOOL_STATUS=false
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
ALLOWED_PATHS=~/my-assistant,~/Documents/Notes,~/.claude
OPENAI_API_KEY=your-key
AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=50
```

### Production with Codex

Full setup with both drivers:

```bash theme={null}
TELEGRAM_BOT_TOKEN=your-token
TELEGRAM_ALLOWED_USERS=your-id,other-id
CLAUDE_WORKING_DIR=/var/lib/claude-assistant
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium
ALLOWED_PATHS=/var/lib/claude-assistant,/home/user/Documents,~/.claude
OPENAI_API_KEY=your-key
CODEX_ENABLED=true
DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
DEFAULT_CODEX_EFFORT=low
META_CODEX_SANDBOX_MODE=workspace-write
META_CODEX_APPROVAL_POLICY=never
AUDIT_LOG_PATH=/var/log/claude-telegram.log
AUDIT_LOG_JSON=true
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=50
RATE_LIMIT_WINDOW=60
```

## Example .env File

```bash theme={null}
# ============ Required ============
TELEGRAM_BOT_TOKEN=123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11
TELEGRAM_ALLOWED_USERS=123456789

# ============ Recommended ============
CLAUDE_WORKING_DIR=~/my-assistant
OPENAI_API_KEY=sk-proj-1234567890abcdef
SHOW_TOOL_STATUS=false
MAIN_PROVIDER=claude
DEFAULT_CLAUDE_MODEL=claude-sonnet-4-6
DEFAULT_CLAUDE_EFFORT=medium

# ============ File Access ============
ALLOWED_PATHS=~/my-assistant,~/Documents/Notes,~/.claude

# ============ Security ============
AUDIT_LOG_PATH=/tmp/claude-telegram-audit.log
AUDIT_LOG_JSON=false
RATE_LIMIT_ENABLED=true
RATE_LIMIT_REQUESTS=20
RATE_LIMIT_WINDOW=60

# ============ Voice ============
TRANSCRIPTION_CONTEXT_FILE=~/my-assistant/transcription-context.txt

# ============ Codex (Optional) ============
# CODEX_ENABLED=true
# MAIN_PROVIDER=codex
# DEFAULT_CODEX_MODEL=gpt-5.3-codex-spark
# DEFAULT_CODEX_EFFORT=low
# META_CODEX_SANDBOX_MODE=workspace-write
# META_CODEX_APPROVAL_POLICY=never
# META_CODEX_NETWORK_ACCESS=false

# ============ Dashboard (Optional) ============
# DASHBOARD_ENABLED=true
# DASHBOARD_AUTH_TOKEN=your-secret-token
```

## Rate Limiting

### RATE\_LIMIT\_ENABLED

Enable per-user inbound Telegram request throttling.

```bash theme={null}
RATE_LIMIT_ENABLED=true
```

Default: `true`. This applies a token bucket before the bot starts processing text, voice, and file messages.

### RATE\_LIMIT\_REQUESTS

How many inbound requests each Telegram user can send per window.

```bash theme={null}
RATE_LIMIT_REQUESTS=20
```

Default: `20` requests. Increase it if you expect a heavier personal usage pattern.

### RATE\_LIMIT\_WINDOW

Time window in seconds.

```bash theme={null}
RATE_LIMIT_WINDOW=60
```

Default: `60` seconds. With the defaults, each user gets 20 inbound requests per 60 seconds.

## Validation

The bot validates on startup:

| Validation                       | Error                                      | Fix                        |
| -------------------------------- | ------------------------------------------ | -------------------------- |
| `TELEGRAM_BOT_TOKEN` missing     | "ERROR: TELEGRAM\_BOT\_TOKEN required"     | Add to `.superturtle/.env` |
| `TELEGRAM_ALLOWED_USERS` missing | "ERROR: TELEGRAM\_ALLOWED\_USERS required" | Add your ID                |
| `RATE_LIMIT_REQUESTS` invalid    | Falls back to 20                           | Use integer                |
| `CODEX_SANDBOX_MODE` invalid     | Warns, falls back to "workspace-write"     | Use valid option           |
| Working directory doesn't exist  | Bot starts but Claude can't access it      | Create directory           |

## Restart required

All variables are read at startup. Restart the bot for any changes to take effect.

## Security Best Practices

1. **Never commit `.superturtle/.env`** — It contains secrets
2. **Use strong tokens** — Telegram and OpenAI provide secure tokens
3. **Limit `ALLOWED_PATHS`** — Only include directories Claude needs
4. **Restrict `TELEGRAM_ALLOWED_USERS`** — Only trusted users
5. **Use read-only sandbox** — For Codex if possible (`read-only` or `workspace-write`)
6. **Enable audit logging** — Always log interactions for review

## Next Steps

* [Security](/config/security) — Full security model and threat assessment
* [Platform Support](/config/platform-support) — macOS/Linux/Windows differences
* [Drivers](/bot/drivers) — Understanding Claude Code vs Codex