Introduction
Whether you’re refactoring legacy code, implementing new features, or debugging complex issues, AI coding assistants can accelerate your development workflow and reduce time-to-delivery. OpenHands is an AI-powered coding framework that acts like a real development partner—it understands complex requirements, navigates entire codebases, writes and modifies code across multiple files, debugs errors, and can even interact with external services. Unlike traditional code completion tools that suggest snippets, OpenHands acts as an autonomous agent capable of carrying out complete development tasks from start to finish.
On the model side, GPT-OSS is OpenAI’s family of open-source large language models built for advanced reasoning and code generation. These models, released under the Apache 2.0 license, bring capabilities that were previously locked behind proprietary APIs into a fully accessible form. GPT-OSS-20B offers fast responses and modest resource requirements, making it well-suited for smaller teams or individual developers running models locally.
GPT-OSS-120B delivers deeper reasoning for complex workflows, large-scale refactoring, and architectural decision-making, and it can be deployed on more powerful hardware for higher throughput. Both models use a mixture-of-experts architecture, activating only the parts of the network needed for a given request, which helps balance efficiency with performance.
In this tutorial will guide you through creating a complete local AI coding setup that combines OpenHands‘ agent capabilities with GPT-OSS models.
Tutorial: Building Your Local AI Coding Agent
Prerequisites
Before we begin, ensure you have the following requirements:
Get a PAT key — To use OpenHands with Clarifai models, you’ll need a Personal Access Token (PAT). Log in or sign up for a Clarifai account, then navigate to your Security settings to generate a new PAT.
Get a model — Clarifai’s Community offers a wide selection of cutting-edge language models that you can run using OpenHands. Browse the community to find a model that best fits your use case. For this example, we’ll use the gpt-oss-120b model.
Install Docker Desktop — OpenHands runs inside a Docker container, so you’ll need Docker installed and running on your system. You can download and install Docker Desktop for your operating system from the official Docker website. Be sure to follow the installation steps specific to your OS (Windows, macOS, or Linux).
Step 1: Pull Runtime Image
OpenHands uses a dedicated Docker image to provide a sandboxed execution environment. You can pull this image from the all-hands-ai Docker registry.
Step 2: Run OpenHands
Start OpenHands using the following comprehensive docker run command.
This command launches a new Docker container running OpenHands with all necessary configurations including environment variables for logging, Docker engine access for sandboxing, port mapping for web interface access on localhost:3000, persistent data storage in the ~/.openhands folder, host communication capabilities, and automatic cleanup when the container exits.
Step 3: Access the Web Interface
After running the docker run command, monitor the terminal for log output. Once the application finishes its startup process, open your preferred web browser and navigate to: http://localhost:3000
At this point, OpenHands is successfully installed and running on your local machine, ready for configuration.
Step 4: Configure OpenHands with GPT-OSS
To configure OpenHands, open its interface and click the Settings (gear icon) in the bottom-left corner of the sidebar.
The Settings page allows you to connect OpenHands to a LLM, which serves as its cognitive engine, and integrate it with GitHub for version control and collaboration.
Connect to GPT-OSS via Clarifai
In the Settings page, go to the LLM tab and toggle the Advanced button.
Fill in the following fields for the model integration:
Custom Model — Enter the Clarifai model URL for GPT-OSS-120B. To ensure OpenAI compatibility, prefix the model path with openai/, followed by the full Clarifai model URL: “openai/https://clarifai.com/openai/chat-completion/models/gpt-oss-120b”
Base URL — Enter Clarifai’s OpenAI-compatible API endpoint: “https://api.clarifai.com/v2/ext/openai/v1”
API Key — Enter your Clarifai PAT.
After filling in the fields, click the Save Changes button at the bottom-right corner of the interface.
While this tutorial focuses on GPT-OSS-120B model, Clarifai’s Community has over 100 open-source and third-party models that you can easily access through the same OpenAI-compatible API. Simply replace the model URL in the Custom Model field with any other model from Clarifai’s catalog to experiment with different AI capabilities and find the one that best fits your development workflow.
Step 5: Integrate with GitHub
Within the same Settings page, navigate to the Integrations tab.
Enter your GitHub token in the provided field, then click Save Changes in the bottom-right corner of the interface to apply the integration
Step 6: Start Building with AI-Powered Development
Next, click the plus (+) Start new conversation button at the top of the sidebar. From there, connect to a repository by selecting your desired repo and its branch.
Once selected, click the Launch button to begin your coding session with full repository access.
In the main interface, use the input field to prompt the agent and begin generating your code. The GPT-OSS-120B model will understand your requirements and provide intelligent, context-aware assistance tailored to your connected repository.
Example prompts to get started:
- Documentation: “Generate a comprehensive README.md file for this repository that explains the project purpose, installation steps, and usage examples.”
- Testing: “Write detailed unit tests for the user authentication functions in the auth.py file, including edge cases and error handling scenarios.”
- Code Enhancement: “Analyze the database connection logic and refactor it to use connection pooling for better performance and reliability.”
OpenHands forwards your request to the configured GPT-OSS-120B model, which responds by generating intelligent code solutions, explanations, and implementations that understand your project context, and once you’re satisfied, you can seamlessly push your code to GitHub directly from the interface, maintaining full version control integration.
Conclusion
You’ve set up a fully functional AI coding agent that runs entirely on your local infrastructure using OpenHands and GPT-OSS-120B models.
If you want to use a model running locally, you can set it up with local runners. For example, you can run the GPT-OSS-20B model locally, expose it as a public API, and use that URL to power your coding agent. Check out the tutorial on running gpt-oss models locally using local runners here.
If you need more computing power, you can deploy gpt-oss models on your own dedicated machines using compute orchestration and then integrate them with your coding agents, giving you greater control over performance and resource allocation.
