# Open Interpreter — User Guide

## 1. Quick Start

Open Interpreter lets language models run code (Python, JavaScript, Shell, and more) directly on your computer. It provides a ChatGPT-like interface in your terminal that can create files, browse the web, analyze data, control your mouse and keyboard, and perform virtually any task your computer can do — all through natural language.

**Key features:**

- Execute Python, JavaScript, Shell, Ruby, R, Java, PowerShell, AppleScript, and HTML code locally
- Connect to any LLM via LiteLLM (OpenAI, Anthropic, Ollama, LM Studio, Azure, and 20+ providers)
- Full internet access and no file-size or runtime limits (unlike ChatGPT's Code Interpreter)
- OS control mode for mouse and keyboard automation via Anthropic's computer use API
- Built-in conversation history with save, load, and resume
- Profile system for reusable configurations
- Server mode with WebSocket and OpenAI-compatible REST endpoints
- Vision support for image-aware models
- Safe mode with semgrep code scanning
- Budget management to cap LLM spending

**Prerequisites:** Python 3.11+

**Install and run:**

```bash
pip install open-interpreter
```

```bash
interpreter
```

**Minimal Python example:**

```python
from interpreter import interpreter

interpreter.chat("What operating system am I using?")
```

```text
I'll check your operating system.

> platform.system()
'Linux'

You are running Linux.
```

> [!TIP]
> Pass a message directly after `interpreter` in your terminal to skip the interactive prompt: `interpreter make me a pomodoro app` enters ultra-fast mode and attempts the task in a single command.

**What to try next:** See Configuration for model setup, Core Usage for terminal and Python workflows, or Common Tasks for real-world recipes.

## 2. Installation

### System Requirements

| Requirement | Minimum |
|---|---|
| Python | 3.11+ |
| pip | Latest recommended |
| OS | Windows, macOS, Linux |
| RAM | 4 GB (8+ GB recommended for local models) |
| Disk | 500 MB (more for local models) |

### Installation Methods

=== "pip (recommended)"
    ```bash
    pip install open-interpreter
    ```

=== "pip with server extras"
    ```bash
    pip install "open-interpreter[server]"
    ```

=== "pip with local model extras"
    ```bash
    pip install "open-interpreter[local]"
    ```

=== "pip with OS control extras"
    ```bash
    pip install "open-interpreter[os]"
    ```

=== "Poetry (development)"
    ```bash
    git clone https://github.com/OpenInterpreter/open-interpreter.git
    cd open-interpreter
    poetry install
    poetry run interpreter
    ```

> [!IMPORTANT]
> If you plan to use `--local` mode, install with `pip install "open-interpreter[local]"`. For `--os` mode, use `pip install "open-interpreter[os]"`. You can combine extras: `pip install "open-interpreter[local,os]"`.

### Platform Installers

Open Interpreter provides one-click installers for users who do not have Python set up:

| Platform | Installer |
|---|---|
| macOS | `installers/oi-mac-installer.sh` — installs pyenv, Python 3.11, and the package |
| Linux | `installers/oi-linux-installer.sh` — installs Rust (if needed), pyenv, Python 3.11, and the package |
| Windows | `installers/oi-windows-installer.ps1` — installs pyenv-win, Rust (if needed), Python 3.11.7, and the package |
| Windows (Conda) | `installers/oi-windows-installer-conda.ps1` — installs Miniconda, creates an `oi` environment, and creates a desktop shortcut |

### Post-Install Verification

```bash
interpreter --version
```

```text
Open Interpreter 0.4.x Developer Preview
```

### Install Troubleshooting

**Q: `poetry install` hangs on dependencies**

Set this environment variable first, then retry:

```bash
export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
poetry install
```

**Q: Import errors for optional features**

Install the appropriate extras group:

```bash
pip install "open-interpreter[local]"   # For --local mode
pip install "open-interpreter[os]"      # For --os mode
pip install "open-interpreter[server]"  # For --server mode
```

**Q: `interpreter` command not found after install**

Ensure your Python scripts directory is on your PATH. On some systems you may need:

```bash
python -m interpreter
```

## 3. Configuration

### Setting Your LLM API Key

Open Interpreter uses LiteLLM under the hood, which means it works with any model provider. Set your API key as an environment variable:

```bash
# OpenAI
export OPENAI_API_KEY=sk-...

# Anthropic
export ANTHROPIC_API_KEY=sk-ant-...
```

Or pass it directly:

```bash
interpreter --api_key "sk-..."
```

### Choosing a Model

```bash
interpreter --model gpt-4o
interpreter --model claude-3-5-sonnet-20240620
interpreter --model ollama/llama3
```

In Python:

```python
from interpreter import interpreter

interpreter.llm.model = "claude-3-5-sonnet-20240620"
interpreter.chat()
```

> [!NOTE]
> Model names follow LiteLLM conventions. For the full list of supported providers and model strings, see [LiteLLM Providers](https://docs.litellm.ai/docs/providers/).

### Common Configuration Options

| Setting | CLI Flag | Python Attribute | Default | Description |
|---|---|---|---|---|
| Model | `--model`, `-m` | `interpreter.llm.model` | `gpt-4o` | LLM to use |
| Auto-run | `--auto_run`, `-y` | `interpreter.auto_run` | `False` | Skip code approval prompts |
| Temperature | `--temperature`, `-t` | `interpreter.llm.temperature` | Provider default | Sampling temperature |
| Context window | `--context_window`, `-cw` | `interpreter.llm.context_window` | Model default | Max context size in tokens |
| Max tokens | `--max_tokens`, `-x` | `interpreter.llm.max_tokens` | Model default | Max output tokens per response |
| Max budget | `--max_budget`, `-b` | `interpreter.llm.max_budget` | None | Spending cap in USD |
| Max output | `--max_output`, `-xo` | `interpreter.max_output` | `2800` | Max chars for code output display |
| Safe mode | `--safe_mode` | `interpreter.safe_mode` | `off` | Code scanning: `off`, `ask`, `auto` |
| Verbose | `--verbose`, `-v` | `interpreter.verbose` | `False` | Show detailed logs |
| Offline | `--offline`, `-o` | `interpreter.offline` | `False` | Disable online features |
| Multi-line | `--multi_line`, `-ml` | `interpreter.multi_line` | `True` | Enable multi-line input (``` delimited) |
| Loop | `--loop` | `interpreter.loop` | `False` | Keep running until task completes |
| Disable telemetry | `--disable_telemetry`, `-dt` | `interpreter.disable_telemetry` | `False` | Turn off anonymous usage stats |
| Speak messages | `--speak_messages`, `-sp` | `interpreter.speak_messages` | `False` | macOS: read responses aloud |
| Vision | `--vision`, `-vi` | — | `False` | Enable vision for supported models |
| OS mode | `--os` | — | `False` | Enable mouse/keyboard control |
| Local | `--local`, `-l` | — | `False` | Interactive local model setup |
| Fast | `--fast`, `-f` | — | `False` | Use `gpt-4o-mini` with concise responses |
| API base | `--api_base`, `-ab` | `interpreter.llm.api_base` | None | Custom API endpoint URL |

### Profiles

Profiles are YAML or Python files that store configuration presets. Open the profiles directory:

```bash
interpreter --profiles
```

The default profile is `default.yaml`. To use a specific profile:

```bash
interpreter --profile my_profile.yaml
```

Built-in profile shortcuts:

| Shortcut | Profile | Description |
|---|---|---|
| `--fast` | `fast.yaml` | Uses `gpt-4o-mini`, concise output |
| `--local` | `local.py` | Interactive local model selection |
| `--vision` | `vision.yaml` | Enables vision capabilities |
| `--os` | `os.py` | OS control mode (mouse/keyboard) |
| `--codestral` | `codestral.py` | Mistral's Codestral model |
| `--llama3` | `llama3.py` | Meta's Llama 3 via Ollama |
| `--groq` | `groq.py` | Groq-hosted models |
| `--assistant` | `assistant.py` | Assistant-style interaction |

To reset a profile to defaults:

```bash
interpreter --reset_profile default.yaml
```

> [!TIP]
> Profiles can be Python files (`.py`) for dynamic configuration. They receive the `interpreter` object and can set any attribute programmatically.

For the complete configuration reference, see the Admin Guide.

## 4. Core Usage

### Terminal Interface

Launch the interactive terminal:

```bash
interpreter
```

You will see a `>` prompt. Type your request in plain language:

```text
> How many files are on my desktop?
```

Open Interpreter will generate code, display it for your review, and ask for approval before running it. Press Enter to approve, or type `n` to reject.

> [!WARNING]
> Code generated by the LLM runs directly on your machine. Always review code before approving, especially commands that modify files, install software, or change system settings. Use `--safe_mode ask` to enable semgrep code scanning before execution.

#### Auto-Run Mode

To skip the approval prompt (use with caution):

```bash
interpreter -y
```

#### Multi-Line Input

Wrap multi-line messages with triple backticks:

```text
> ```
  I need you to:
  1. Create a directory called "project"
  2. Initialize a git repo in it
  3. Create a README.md
  ```
```

#### Magic Commands

During an interactive session, prefix commands with `%`:

| Command | Description |
|---|---|
| `%help` | Show all available commands |
| `%verbose [true/false]` | Toggle verbose/debug mode |
| `%reset` | Reset the current conversation |
| `%undo` | Remove the last user message and AI response |
| `%save_message [path]` | Save messages to JSON (default: `messages.json`) |
| `%load_message [path]` | Load messages from JSON |
| `%tokens [prompt]` | Show token count and estimated cost |
| `%info` | Display system and interpreter diagnostics |
| `%jupyter` | Export conversation to a Jupyter notebook |
| `%markdown [path]` | Export conversation to Markdown |
| `%auto_run [true/false]` | Toggle auto-run mode mid-session |
| `%% [command]` | Run a shell command directly |

> [!NOTE]
> `%debug` is a deprecated alias for `%verbose`. Use `%verbose` instead.

### Python API

Import the pre-configured `interpreter` instance:

```python
from interpreter import interpreter
```

#### Single Command

```python
interpreter.chat("Plot AAPL and META's normalized stock prices")
```

#### Interactive Chat

```python
interpreter.chat()  # Opens interactive loop
```

#### Streaming Responses

```python
for chunk in interpreter.chat("What OS am I using?", display=False, stream=True):
    print(chunk)
```

Each chunk is a dictionary in LMC (Language Model Computer) message format:

```python
{"role": "assistant", "type": "message", "content": "I'll check..."}
{"role": "assistant", "type": "code", "format": "python", "content": "import platform\nprint(platform.system())"}
{"role": "computer", "type": "console", "format": "output", "content": "Linux"}
```

#### Conversation Management

```python
# Save conversation
messages = interpreter.chat("My name is Alice.")

# Reset
interpreter.messages = []

# Resume from saved conversation
interpreter.messages = messages
interpreter.chat("What's my name?")  # Remembers "Alice"
```

#### Customizing the System Message

```python
interpreter.system_message += """
Run shell commands with -y so the user doesn't have to confirm.
"""
```

### Running Local Models

Launch the interactive local model setup:

```bash
interpreter --local
```

This presents a menu to select a provider:

| Provider | How It Works |
|---|---|
| **Ollama** | Lists installed models; can download new ones. Sets `interpreter.llm.model = "ollama/{model}"` |
| **Llamafile** | Downloads and runs a llamafile binary. Sets API base to `http://localhost:8080/v1` |
| **LM Studio** | Connects to LM Studio's local server at `http://localhost:1234/v1` |
| **Jan** | Connects to Jan's local API at `http://localhost:1337/v1` |

To connect manually to any OpenAI-compatible local server:

```bash
interpreter --api_base "http://localhost:1234/v1" --api_key "dummy" --model "openai/my-model"
```

In Python:

```python
interpreter.offline = True
interpreter.llm.model = "openai/x"
interpreter.llm.api_key = "dummy"
interpreter.llm.api_base = "http://localhost:1234/v1"
interpreter.chat()
```

> [!TIP]
> For machines with less than 10 GB RAM, set a smaller context window: `interpreter --local --max_tokens 1000 --context_window 3000`.

### OS Control Mode

OS mode lets Open Interpreter control your mouse and keyboard using Anthropic's computer use API:

```bash
interpreter --os
```

This requires an `ANTHROPIC_API_KEY` environment variable. OS mode uses Claude 3.5 Sonnet by default and operates in a loop where the model can take screenshots, click, type, and run bash commands.

> [!CAUTION]
> OS mode gives the AI full control of your mouse and keyboard. Move your mouse to any corner of the screen to trigger an emergency exit. Always supervise OS mode sessions.

### Server Mode

Start Open Interpreter as an HTTP/WebSocket server:

```bash
interpreter --server
```

The server starts on `http://127.0.0.1:8000` by default. It exposes WebSocket and REST endpoints for programmatic control. See the Admin Guide for the full API reference.

## 5. Common Tasks

### Task 1: Analyze a CSV File

**Goal:** Summarize a data file and create a chart.

```text
> Load sales_data.csv, show me the top 5 products by revenue, and plot a bar chart
```

Open Interpreter will use pandas to read the file, compute aggregations, and use matplotlib to generate the chart.

### Task 2: Batch Rename Files

**Goal:** Rename all `.jpeg` files to `.jpg` in a directory.

```text
> Rename all .jpeg files in ~/Photos to .jpg
```

### Task 3: Create a Simple Web App

**Goal:** Build a Flask "Hello World" app.

```text
> Create a simple Flask web app that says "Hello World" and run it on port 5000
```

### Task 4: Search and Summarize the Web

**Goal:** Research a topic and create a summary.

```text
> Research the latest developments in quantum computing and write a summary to quantum_summary.md
```

### Task 5: Edit Images

**Goal:** Resize all images in a folder.

```text
> Resize all PNG images in ./images to 800x600 and save them to ./resized
```

### Task 6: Database Queries

**Goal:** Query a local SQLite database.

```text
> Open my_database.db and show me the schema of all tables, then find the 10 most recent orders
```

### Task 7: Set Up a Project

**Goal:** Initialize a new Python project.

```text
> Create a new Python project called "my_app" with a virtual environment, install requests and flask, and create a basic project structure
```

### Task 8: Control Budget Spending

**Goal:** Limit LLM API costs for a session.

```python
interpreter.llm.max_budget = 5.00  # USD
interpreter.chat()
```

> [!WARNING]
> Budget tracking depends on LiteLLM's `cost_per_token()` function and may not be perfectly accurate for all providers. Monitor your provider dashboard for authoritative spend data.

### Task 9: Export Conversation to Jupyter Notebook

During an interactive session:

```text
> %jupyter
```

```text
Jupyter notebook file exported to /Users/you/Downloads/open-interpreter-05-07-26-0230PM.ipynb
```

### Task 10: Resume a Previous Conversation

```bash
interpreter --conversations
```

This displays a menu of saved conversations. Select one to resume where you left off.

## 6. Troubleshooting

### Diagnostic Decision Tree

1. **Is the error about an API key?** → Check your environment variable is set correctly
2. **Is it a connection error?** → Verify your API base URL and network access
3. **Is code failing to execute?** → Check language runtime is installed (Python, Node, etc.)
4. **Is the model producing garbage?** → Try a different model or adjust context_window/max_tokens
5. **Is it hanging?** → Press `CTRL-C` to interrupt; sudo commands may hang indefinitely (see #1694 below)

### Error: API key not set or invalid

**Cause:** The environment variable for your LLM provider is missing or incorrect.

**Solution:**

1. Set the appropriate environment variable:
   ```bash
   export OPENAI_API_KEY=sk-your-key-here     # Linux/macOS
   setx OPENAI_API_KEY sk-your-key-here        # Windows (restart terminal after)
   ```
2. Or pass it directly: `interpreter --api_key "your-key"`

**Prevention:** Add the export to your shell profile (`~/.bashrc`, `~/.zshrc`).

### Error: `You ran out of current quota for OpenAI's API`

**Cause:** Confusion between API providers. Using a Groq API key but the error references OpenAI. (Community issue #1706)

**Solution:**

1. Verify you are setting the correct model string: `interpreter --model groq/llama3-8b-8192`
2. Ensure you set the `GROQ_API_KEY`, not `OPENAI_API_KEY`
3. If using `--api_base`, the model prefix must match: use `openai/` prefix for custom endpoints

**Prevention:** Always match the model prefix to your provider.

### Error: sudo commands hang indefinitely

**Cause:** Open Interpreter's subprocess handling cannot pass interactive sudo password prompts. (Community issue #1694)

**Solution:**

1. Run the command requiring sudo outside Open Interpreter, or
2. Use `sudo -S` with piped input (security risk), or
3. Configure passwordless sudo for specific commands

**Prevention:** Avoid asking Open Interpreter to run sudo commands in automated/auto_run mode.

### Error: `.deb` package fails to install

**Cause:** Cross-device hard link error for icon file. (Community issue #1703)

**Solution:** Install via pip instead of the `.deb` package:

```bash
pip install open-interpreter
```

### Error: `callable auto_run silently breaks`

**Cause:** When `auto_run` is set as a callable (instead of a boolean), the confirmation prompt is never shown and rejected commands vanish silently. (Community issue #1696)

**Solution:** Ensure `auto_run` is set to a boolean:

```python
interpreter.auto_run = True   # Correct
# interpreter.auto_run = my_function  # Incorrect
```

### Error: `Xcode is not installed`

**Cause:** macOS requires Xcode Command Line Tools for Llamafile mode.

**Solution:**

```bash
xcode-select --install
```

**Prevention:** Use Ollama or LM Studio as local model providers on macOS if Xcode installation is not desirable.

### Error: Truncated command output references non-existent method

**Cause:** When output exceeds `max_output` characters, the truncation message references `get_last_output()` which is not always available. (Community issue #1695)

**Solution:** Increase `max_output` to avoid truncation, or break tasks into smaller steps:

```bash
interpreter --max_output 10000
```

### Error: `keyboard.write` fails on macOS background service

**Cause:** macOS restricts keyboard input from background processes. The `interpreter.computer.keyboard.write` method requires accessibility permissions. (Community issue #1292)

**Solution:** Grant accessibility permissions to the terminal application running Open Interpreter in System Settings → Privacy & Security → Accessibility.

### Error: `poetry install` hangs

**Cause:** Python keyring backend interfering with poetry's dependency resolution.

**Solution:**

```bash
export PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring
poetry install
```

### Error: Ubuntu can't install using instructions

**Cause:** System Python may not have pip, or pip-installed scripts may not be on PATH. (Community issue #1689)

**Solution:**

```bash
sudo apt install python3-pip
pip install open-interpreter
# If 'interpreter' command not found:
python3 -m interpreter
```

## 7. FAQ

**Q: How does Open Interpreter differ from ChatGPT's Code Interpreter?**

Open Interpreter runs locally on your machine with full internet access, no file-size limits, no runtime limits, and access to all installed packages. ChatGPT's Code Interpreter runs in a sandboxed cloud environment with significant restrictions.

**Q: Is it safe to use auto-run mode (`-y`)?**

Auto-run mode bypasses code review. Use it only when you trust the task and are monitoring output. Consider using `--safe_mode ask` or `--safe_mode auto` alongside auto-run to enable semgrep code scanning for an extra layer of protection.

**Q: Can I use Open Interpreter with local models (no API key needed)?**

Yes. Run `interpreter --local` and select from Ollama, Llamafile, LM Studio, or Jan. All run entirely on your machine with no API key required.

**Q: How do I disable telemetry?**

Three ways:

```bash
interpreter --disable_telemetry           # CLI flag
```

```python
interpreter.disable_telemetry = True      # Python
```

```bash
export DISABLE_TELEMETRY=true             # Environment variable
```

Telemetry is anonymous usage statistics sent to PostHog. It helps the team understand usage patterns.

**Q: What programming languages can Open Interpreter execute?**

Python, JavaScript, Shell (bash/zsh), Ruby, R, Java, PowerShell, AppleScript, HTML, and React. Languages are implemented as plugins in `interpreter/core/computer/terminal/languages/`.

**Q: How do I use vision mode?**

```bash
interpreter --vision
```

Or use a model that supports vision and pass image paths in your messages. The model must have `supports_vision` set to `True`.

**Q: Can I set a spending limit?**

Yes. Use `--max_budget` to cap spending in USD:

```bash
interpreter --max_budget 10.00
```

Or check token costs during a session:

```text
> %tokens
```

**Q: How do I resume a past conversation?**

```bash
interpreter --conversations
```

Select from the list of saved conversations. Conversations are stored as JSON files in `~/.local/share/Open Interpreter/conversations/` (path varies by OS).

**Q: Can I run Open Interpreter as an API server?**

Yes. See the Admin Guide for server mode details:

```bash
interpreter --server
```

**Q: How do I contribute conversations for training?**

Set `--contribute_conversation` or use model `i`:

```bash
interpreter --model i
```

Conversations with the `i` model are sent to Open Interpreter for training their open-source language model.

**Q: What is the LMC message format?**

LMC (Language Model Computer) is Open Interpreter's streaming message protocol. Each message is a dictionary with `role`, `type`, `format`, and `content` fields. See the Admin Guide for the complete protocol specification.

---

_Generated May 2026 from openinterpreter/open-interpreter at 06c796a. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._