self-operating-computer README

The project's README from github.com/OthersideAI/self-operating-computer. As one markdown file: README.md.

ome

Self-Operating Computer Framework

A framework to enable multimodal models to operate a computer.

Using the same inputs and outputs as a human operator, the model views the screen and decides on a series of mouse and keyboard actions to reach an objective. Released Nov 2023, the Self-Operating Computer Framework was one of the first examples of full computer-use.

Key Features

Demo

https://github.com/OthersideAI/self-operating-computer/assets/42594239/9e8abc96-c76a-46fb-9b13-03678b3c67e0

Run Self-Operating Computer

  1. Install the project
pip install self-operating-computer
  1. Run the project
operate
  1. Enter your OpenAI Key: If you don't have one, you can obtain an OpenAI key here. If you need you change your key at a later point, run vim .env to open the .env and replace the old key.
  1. Give Terminal app the required permissions: As a last step, the Terminal app will ask for permission for "Screen Recording" and "Accessibility" in the "Security & Privacy" page of Mac's "System Preferences".

Using operate Modes

OpenAI models

The default model for the project is gpt-4o which you can use by simply typing operate. To try running OpenAI's new o1 model, use the command below.

operate -m o1-with-ocr

To experiment with OpenAI's latest gpt-4.1 model, run:

operate -m gpt-4.1-with-ocr

Multimodal Models -m

Try Google's gemini-pro-vision by following the instructions below. Start operate with the Gemini model

operate -m gemini-pro-vision

Enter your Google AI Studio API key when terminal prompts you for it If you don't have one, you can obtain a key here after setting up your Google AI Studio account. You may also need authorize credentials for a desktop application. It took me a bit of time to get it working, if anyone knows a simpler way, please make a PR.

Try Claude -m claude-3

Use Claude 3 with Vision to see how it stacks up to GPT-4-Vision at operating a computer. Navigate to the Claude dashboard to get an API key and run the command below to try it. 

operate -m claude-3

Try qwen -m qwen-vl

Use Qwen-vl with Vision to see how it stacks up to GPT-4-Vision at operating a computer. Navigate to the Qwen dashboard to get an API key and run the command below to try it. 

operate -m qwen-vl

Try LLaVa Hosted Through Ollama -m llava

If you wish to experiment with the Self-Operating Computer Framework using LLaVA on your own machine, you can with Ollama!
Note: Ollama currently only supports MacOS and Linux. Windows now in Preview

First, install Ollama on your machine from https://ollama.ai/download.

Once Ollama is installed, pull the LLaVA model:

ollama pull llava

This will download the model on your machine which takes approximately 5 GB of storage.

When Ollama has finished pulling LLaVA, start the server:

ollama serve

That's it! Now start operate and select the LLaVA model:

operate -m llava

Important: Error rates when using LLaVA are very high. This is simply intended to be a base to build off of as local multimodal models improve over time.

Learn more about Ollama at its GitHub Repository

Voice Mode --voice

The framework supports voice inputs for the objective. Try voice by following the instructions below. Clone the repo to a directory on your computer:

git clone https://github.com/OthersideAI/self-operating-computer.git

Cd into directory:

cd self-operating-computer

Install the additional requirements-audio.txt

pip install -r requirements-audio.txt

Install device requirements For mac users:

brew install portaudio

For Linux users:

sudo apt install portaudio19-dev python3-pyaudio

Run with voice mode

operate --voice

Optical Character Recognition Mode -m gpt-4-with-ocr

The Self-Operating Computer Framework now integrates Optical Character Recognition (OCR) capabilities with the gpt-4-with-ocr mode. This mode gives GPT-4 a hash map of clickable elements by coordinates. GPT-4 can decide to click elements by text and then the code references the hash map to get the coordinates for that element GPT-4 wanted to click.

Based on recent tests, OCR performs better than som and vanilla GPT-4 so we made it the default for the project. To use the OCR mode you can simply write:

operate or operate -m gpt-4-with-ocr will also work.

Set-of-Mark Prompting -m gpt-4-with-som

The Self-Operating Computer Framework now supports Set-of-Mark (SoM) Prompting with the gpt-4-with-som command. This new visual prompting method enhances the visual grounding capabilities of large multimodal models.

Learn more about SoM Prompting in the detailed arXiv paper: here.

For this initial version, a simple YOLOv8 model is trained for button detection, and the best.pt file is included under model/weights/. Users are encouraged to swap in their best.pt file to evaluate performance improvements. If your model outperforms the existing one, please contribute by creating a pull request (PR).

Start operate with the SoM model

operate -m gpt-4-with-som

Contributions are Welcomed!:

If you want to contribute yourself, see CONTRIBUTING.md.

Feedback

For any input on improving this project, feel free to reach out to Josh on Twitter.

Join Our Discord Community

For real-time discussions and community support, join our Discord server.

Follow HyperWriteAI for More Updates

Stay updated with the latest developments:

Compatibility

OpenAI Rate Limiting Note

The gpt-4o model is required. To unlock access to this model, your account needs to spend at least $5 in API credits. Pre-paying for these credits will unlock access if you haven't already spent the minimum $5.
Learn more here

self-operating-computer (OthersideAI/self-operating-computer)

gpt-4
Searching Database…

10.3K ·GitHub
Self-operating-computer
What is this?A framework that lets a multimodal AI model operate your computer: it views the screen and issues mouse and keyboard actions to reach the objective you give it. One of the first full computer-use projects (Nov 2023).
So how does it actually drive the machine — is it a separate app?No, it's a Python framework you run from your terminal with the command 'operate'. It takes control of your real mouse and keyboard based on what it sees on your screen.
How do I get it running?Install the Python package, then run 'operate' and paste your OpenAI API key (it's stored in a .env file you can edit later). On macOS, Terminal also needs Screen Recording and Accessibility permissions in System Preferences.
Which AI models can power it — is an OpenAI key the only option?No, it's built for various multimodal models: GPT-4o, GPT-4.1, o1, Gemini Pro Vision, Claude 3, Qwen-VL, and LLaVa through Ollama. You enter whichever provider's API key you're prompted for; GPT-4o is the default.
Any catch before the OpenAI modes will work?Yes, the vision model it relies on is gated: your OpenAI account must have spent at least $5 in API credits, so you may need to pre-pay that minimum even for a quick trial.
Does it work on Windows, or is it Mac-only?All three major desktops: Mac OS, Windows, and Linux, though on Linux you need an X server installed. The local-model route via Ollama only covers macOS and Linux.
Can I run it with a local model and skip cloud APIs?Yes, in LLaVA mode: install Ollama, pull LLaVA (about 5 GB), start the Ollama server and run 'operate -m llava'. Fair warning: error rates are very high right now; the README calls it a base to build on as local models improve.
How does it know where to click?The default mode, gpt-4-with-ocr, gives GPT-4 a hash map of clickable elements with their coordinates, so it can pick a target by text and the code resolves the coordinates. Recent tests showed OCR beating Set-of-Mark and vanilla GPT-4, which is why it's the default.
What is Set-of-Mark prompting in this project?The -m gpt-4-with-som mode: a visual prompting technique that improves a model's visual grounding. A YOLOv8 model trained for button detection provides the marks, with best.pt weights under model/weights/ that you can swap for your own.
Can I give it goals by voice?Yes, run it with --voice. Voice needs extra setup after cloning the repo: install requirements-audio.txt plus the device-specific requirements (there are separate steps for Mac and Linux).
What are similar projects?Agent-S, hive, qwen-code, aider, brigade, OmniParser, typesafe-computer-use, PentestGPT
Which topics is it in?gpt-4o, gemini-api, screen-recording, desktop-automation, gui-automation, gpt-4, vision-language-model, openai-api, voice, computer-use, ocr, autonomous-agents
Creator
OthersideAI
Size
12.6 MB
Stars
10.3K
Updated
CommitSep 19Releasev1.5.8Feb 28
Age
2y
Commits · 90 Days