# AsyncInterpreter vs OpenInterpreter: Architecture and Usage Differences in Open Interpreter

> Explore AsyncInterpreter vs OpenInterpreter, understanding their architecture and usage. Discover how AsyncInterpreter offers non-blocking execution for web apps using FastAPI and WebSockets.

- Repository: [Open Interpreter/open-interpreter](https://github.com/openinterpreter/open-interpreter)
- Tags: architecture
- Published: 2026-03-05

---

**AsyncInterpreter extends OpenInterpreter to provide non-blocking, network-ready execution via FastAPI and WebSockets, while OpenInterpreter operates synchronously for CLI-based interactions.**

The `openinterpreter/open-interpreter` repository provides two primary Python classes for executing code-generating AI interactions. Understanding the difference between **AsyncInterpreter** and **OpenInterpreter** is essential for choosing the right architecture for your application, whether you need a simple command-line interface or a scalable network service.

## Core Architecture Differences

### OpenInterpreter: The Synchronous Foundation

`OpenInterpreter` (defined in [`interpreter/core/core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/core.py)) serves as the core, synchronous implementation. It manages conversation state through `self.messages` and executes chat rounds via `self._respond_and_store()` → `respond()` → LLM → computer modules.

Key characteristics include:

- **Blocking I/O**: Methods like `chat()` and `respond()` execute in the calling thread, waiting for LLM responses and code execution to complete before returning.
- **CLI Integration**: The class is instantiated directly in [`interpreter/terminal_interface/start_terminal_interface.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/terminal_interface/start_terminal_interface.py) as `interpreter = OpenInterpreter()`, powering the terminal interface.
- **Direct Execution**: Code runs locally with immediate feedback, suitable for interactive scripting and local automation.

### AsyncInterpreter: The Asynchronous Extension

`AsyncInterpreter` (defined in [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py)) inherits from `OpenInterpreter` (`class AsyncInterpreter(OpenInterpreter)`) to add non-blocking, network-capable operations.

Key characteristics include:

- **Async I/O Model**: Uses `janus.Queue` to bridge sync and async worlds, with `input` and `output` methods for streaming communication.
- **Server Integration**: Bundles a FastAPI/WebSocket server (`Server` class) exposing HTTP routes and WebSocket endpoints for remote clients.
- **Acknowledgment Protocol**: Supports `require_acknowledge` flag where output chunks receive unique IDs and clients must acknowledge receipt.
- **OpenAI Compatibility**: Provides OpenAI-compatible endpoints (`/openai/chat/completions`) for integration with existing tooling.

## Feature Comparison

| Feature | OpenInterpreter (Sync) | AsyncInterpreter |
|---------|------------------------|------------------|
| **Inheritance** | Stand-alone class | Sub-class of `OpenInterpreter` |
| **I/O Model** | Blocking calls (`chat`, `respond`) | Async methods with `janus.Queue` |
| **Server Support** | CLI only | FastAPI/WebSocket server included |
| **Acknowledgment** | Not required | Optional `require_acknowledge` with chunk IDs |
| **Message Flow** | Direct calls → immediate response | JSON chunks over WebSocket with buffering |
| **Running Mode** | `terminal_interface` | Background service (`async_interpreter.server.run()`) |
| **Configuration** | CLI flags (`verbose`, `debug`) | Environment variables (`INTERPRETER_ID`, `INTERPRETER_REQUIRE_ACKNOWLEDGE`) |
| **Source File** | [`interpreter/core/core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/core.py) | [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py) |

## Implementation Details

### Source File Locations

The synchronous implementation resides in [`interpreter/core/core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/core.py), defining the `OpenInterpreter` class with methods like `_respond_and_store()` and `respond()`. The asynchronous extension lives in [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py), where `AsyncInterpreter` inherits from `OpenInterpreter` and the `Server` class handles FastAPI routing.

### Method Signatures and I/O Models

**OpenInterpreter** uses direct method calls:

```python
from interpreter.core.core import OpenInterpreter

interpreter = OpenInterpreter(auto_run=True, verbose=True)
response = interpreter.chat("List files in current directory", display=False)

```

**AsyncInterpreter** uses async queues:

```python
from interpreter.core.async_core import AsyncInterpreter

async_interp = AsyncInterpreter()

# Input and output are async generators/queues

async for chunk in async_interp.output():
    print(chunk.get("content", ""), end="")

```

## Practical Usage Examples

### Standard Synchronous Usage

For local scripting and CLI interactions, instantiate `OpenInterpreter` directly:

```python
from interpreter.core.core import OpenInterpreter

# Create instance with configuration

interpreter = OpenInterpreter(auto_run=True, verbose=True)

# Execute chat synchronously

response = interpreter.chat("List the files in the current directory.", display=False)
print(response[-1]["content"])

```

*Source:* [`interpreter/core/core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/core.py)

### Asynchronous WebSocket Implementation

For network-based applications, use `AsyncInterpreter` with its built-in server:

```python
import asyncio
import json
import websockets
from interpreter.core.async_core import AsyncInterpreter

async def run():
    # Initialize async interpreter with server

    async_interp = AsyncInterpreter(auto_run=False)
    
    # Start server in background

    asyncio.create_task(async_interp.server.run())
    
    # Connect to WebSocket endpoint

    uri = f"ws://{async_interp.server.host}:{async_interp.server.port}/"
    async with websockets.connect(uri) as ws:
        # Send start chunk

        await ws.send(json.dumps({"role": "user", "start": True}))
        
        # Send message content

        await ws.send(json.dumps({
            "role": "user", 
            "type": "message",
            "content": "What time is it?"
        }))
        
        # Send end chunk

        await ws.send(json.dumps({"role": "user", "end": True}))
        
        # Receive streamed responses

        while True:
            data = await ws.recv()
            chunk = json.loads(data)
            print(chunk.get("content", ""), end="")
            
            if chunk.get("type") == "status" and chunk.get("content") == "complete":
                break

asyncio.run(run())

```

*Key components:* `AsyncInterpreter.input` accumulates incoming chunks, while `AsyncInterpreter.output` yields queued responses. The `Server` class manages FastAPI routing and WebSocket connections.

*Source:* [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py)

### OpenAI-Compatible Endpoint

The async server provides OpenAI-compatible REST endpoints for integration with existing tools:

```bash
curl -X POST http://127.0.0.1:8000/openai/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
        "model": "gpt-4",
        "messages": [
          {"role": "user", "content": "Create a folder called test and show its path."}
        ],
        "stream": false
      }'

```

The `chat_completion` function in [`async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/async_core.py) forwards requests to the underlying `AsyncInterpreter` instance and formats responses according to the OpenAI API specification.

*Source:* [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py) – `chat_completion` function

## Summary

- **OpenInterpreter** provides synchronous, blocking execution ideal for CLI scripts and local automation, managing conversation state through direct method calls in [`interpreter/core/core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/core.py).

- **AsyncInterpreter** inherits from OpenInterpreter in [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py) to add non-blocking I/O via `janus.Queue`, enabling network deployment through a built-in FastAPI/WebSocket server.

- **Key differentiators** include the I/O model (blocking vs. async queues), server capabilities (none vs. FastAPI/WebSocket), acknowledgment protocols, and OpenAI-compatible endpoints available only in the async variant.

- **Selection criteria**: Use **OpenInterpreter** for local, script-based workflows; use **AsyncInterpreter** for remote clients, browser-based interfaces, or when integrating with existing OpenAI-compatible tooling.

## Frequently Asked Questions

### Can I use AsyncInterpreter without running the server?

Yes, though `AsyncInterpreter` is designed for network usage, you can instantiate it without starting the server by using its `input` and `output` methods directly with async queues. However, for purely local synchronous scripts, `OpenInterpreter` provides a simpler API without the overhead of async I/O management.

### Does AsyncInterpreter support all the same configuration options as OpenInterpreter?

Yes, since `AsyncInterpreter` inherits from `OpenInterpreter` in [`interpreter/core/async_core.py`](https://github.com/openinterpreter/open-interpreter/blob/main/interpreter/core/async_core.py), it supports all base configuration flags like `auto_run`, `verbose`, and `debug`. Additionally, it introduces server-specific environment variables such as `INTERPRETER_ID`, `INTERPRETER_REQUIRE_ACKNOWLEDGE`, and `INTERPRETER_INSECURE_ROUTES` for network deployment scenarios.

### Is the WebSocket protocol in AsyncInterpreter compatible with standard OpenAI clients?

No, the native WebSocket protocol uses a custom JSON chunk format with `role`, `type`, and `content` fields. However, `AsyncInterpreter` provides an OpenAI-compatible HTTP endpoint at `/openai/chat/completions` that accepts standard OpenAI API request formats and returns responses in the expected JSON structure, making it compatible with existing OpenAI client libraries.

### Which class should I use for a Jupyter Notebook environment?

For Jupyter Notebooks, `OpenInterpreter` is typically sufficient and easier to use because it operates synchronously and integrates naturally with the notebook's cell execution model. However, if you need to serve the interpreter to multiple notebook users simultaneously or access it remotely via HTTP/WebSocket, `AsyncInterpreter` with its server capabilities would be the appropriate choice.