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:

pip install open-interpreter

interpreter

Minimal Python example:

from interpreter import interpreter

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

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

Installation Methods

pip (recommended)

pip install open-interpreter

pip with server extras

pip install "open-interpreter[server]"

pip with local model extras

pip install "open-interpreter[local]"

pip with OS control extras

pip install "open-interpreter[os]"

Poetry (development)

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:

Post-Install Verification

interpreter --version

Open Interpreter 0.4.x Developer Preview

Install Troubleshooting

Q: poetry install hangs on dependencies

Set this environment variable first, then retry:

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

Q: Import errors for optional features

Install the appropriate extras group:

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:

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:

# OpenAI
export OPENAI_API_KEY=sk-...

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

Or pass it directly:

interpreter --api_key "sk-..."

Choosing a Model

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

In 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.

Common Configuration Options

Profiles

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

interpreter --profiles

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

interpreter --profile my_profile.yaml

Built-in profile shortcuts:

To reset a profile to defaults:

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:

interpreter

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

> 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):

interpreter -y

Multi-Line Input

Wrap multi-line messages with triple backticks:

> ```
  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

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

Interactive Chat

interpreter.chat()  # Opens interactive loop

Streaming Responses

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:

{"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

# 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

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:

interpreter --local

This presents a menu to select a provider:

To connect manually to any OpenAI-compatible local server:

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

In 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:

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:

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.

> 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.

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

Task 3: Create a Simple Web App

Goal: Build a Flask "Hello World" app.

> 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.

> 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.

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

Task 6: Database Queries

Goal: Query a local SQLite database.

> 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.

> 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.

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:

> %jupyter

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

Task 10: Resume a Previous Conversation

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:

   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:

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:

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:

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:

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:

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:

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:

interpreter --disable_telemetry           # CLI flag

interpreter.disable_telemetry = True      # Python

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?

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:

interpreter --max_budget 10.00

Or check token costs during a session:

> %tokens

Q: How do I resume a past conversation?

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:

interpreter --server

Q: How do I contribute conversations for training?

Set --contribute_conversation or use model i:

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.