Beginner to expert: your first 60 seconds with OpenCode
Installation and first setup in a blink: how to start using opencode for your own projects. Part 2 of the series.
Beginner to expert: your first 60 seconds with OpenCode
Installation and first setup in a blink: how to start using opencode for your own projects. Part 2 of the series.
Getting started with OpenCode is faster than making a cup of coffee.
In this guide, I will show you how to install it, connect it to a free AI “brain,” and run your very first command.
You don’t need to be a coding wizard; you just need a terminal and a bit of curiosity.
Table of Contents
The Thrill of the New Install
Step 1: Getting the Software onto Your Machine
What on Earth is a Package Manager?
Step 2: The First Launch and the TUI
Step 3: Connecting Your First "Brain" (For Free!)
Step 4: Your Very First Command
Troubleshooting: When Things Don't Go According to Plan
Conclusion: You are Now an Agent UserBy the way, this is a Series of 6 articles:
**Part 1 — The OpenCode revolution: more than just another chatbot Part 2 — Beginner to expert: your first 60 seconds with OpenCode* Part 3 — Teaching your Agent: mastering context with AGENTS.md Part 4 — The toolkit: Commands and Skills in OpenCode Part 5 — Your private AI Agency: the local powerhouse Part 6 — Advanced Orchestration: multi-agent systems and plugins*
The Thrill of the New Install
There is a specific kind of joy that comes from installing a new piece of software. It is that moment of anticipation, where you wonder, “What can this actually do for me?” I remember the early days of installing specialized software on my old workstation. You would insert the floppy disk, wait for the progress bar, and then, suddenly, a new icon would appear.
Installing an AI agent like OpenCode feels similar, but with a modern twist. We are installing a capability. We are setting the stage for a partnership with an intelligent system.
In this article, I am going to walk you through that process. I will assume nothing. We will start from a blank slate and, within minutes, you will be commanding an AI to write code for you.
Step 1: Getting the Software onto Your Machine
Depending on what kind of computer you are using, the way you “get” OpenCode will differ slightly. Think of it like different ways to order a pizza. You can call the shop, use an app, or walk in. The result is the same: you get your pizza.
Prerequisites
You need to have Node.js and Git installed. If you already have Chocolatey you can read all the steps here.
Node.js is the standard installation method for Windows (and in handy for future upgrades with MCP and tools). Git is the World standard for Software Version Control, used to manage your repository (code or documents).
My suggestion, if you are on Windows, is to use GIT Bash as a terminal editor and the main reason is…
👉 Tip: most of the agents will try to run
unix/linuxlike commands to browse files, search for patterns, read your files. The Windows Terminal and Powershell struggle to parse the commands. GIT bash is fully able to understand them.
- Download and install Node.js from here
- Download and install Git from here
For macOS and Linux Users
If you use a Mac or a Linux machine, you likely have access to something called “Homebrew.” If you don’t know what that is, don’t worry. It is essentially a massive, automated warehouse for software. Instead of hunting for a download button on a website, you just tell Homebrew what you want, and it finds it, downloads it, and installs it for you.
Open your terminal (on a Mac, you can find this in your Applications/Utilities folder) and type this single line:
brew install anomalyco/tap/opencode
That’s it. Just press Enter and watch the magic happen.
For Windows Users
Windows users, you have a few options. The easiest way, if you are already familiar with web development tools, is using npm. You might have heard of npm before; it is the "Node Package Manager," which is another way of saying it is a very reliable delivery service for software.
And since I already asked you to install node.js, you have all you need.
Open your Command Prompt or PowerShell and type:
npm install -g opencode-ai
If you prefer a different approach, you can also use “Chocolatey” or “Scoop,” which are similar to Homebrew but built specifically for the Windows ecosystem.
Once the installation finishes, we need to make sure everything is working. Type this command:
oppencode --version
If you see a version number pop up, congratulations! You have successfully conquered the first hurdle. You are officially an OpenCode user.
Few commands you need to know: start with opencode -h to get the list of commands as displayed above.
You can for example upgrade your version using opencode upgrade
What on Earth is a Package Manager?
I realize that terms like brew, npm, or curl might sound like gibberish if you haven't spent much time in the terminal. Let me explain them using an analogy from our daily lives.
Imagine you want to build a massive Lego castle. You could go to a store, find every individual brick, buy them one by one, and bring them home. That would be exhausting and prone to error.
Instead, you use a catalog. You look up “Castle Set #402,” and a specialized service delivers the entire organized kit to your door.
In the world of computing, a “Package Manager” is that catalog and delivery service. Instead of you searching the internet for opencode.zip, finding the right version for your operating system, and manually moving files into the right folders, you simply tell the package manager: "I want OpenCode." The manager handles the searching, the downloading, and the heavy lifting of placing the files exactly where they need to go. It is safer, faster, and much less headache-inducing.
Step 2: The First Launch and the TUI
Now that the software is on your machine, it is time to meet it. Navigate to any folder on your computer where you might keep projects (for example, a folder named Documents/NewProject) and type:
opencode
Suddenly, your terminal will transform. The plain text will disappear, replaced by a structured, interactive interface. This is what we call a TUI, or “Terminal User Interface.”
Think of it like this: a standard terminal is like a blank notepad. You write a line, it responds. A TUI is more like a dashboard. It has menus, it has sections, and it is designed for you to interact with it easily using your keyboard.
Don’t be intimidated by the change. You are still in your terminal, but you are now in a specialized “command center” for your AI agent.
Step 3: Connecting Your First “Brain” (For Free!)
When you first launch OpenCode, it is like having a very capable body but no brain. It knows how to move around your files, but it doesn’t actually “know” anything yet. To make it smart, we need to connect it to an AI model.
Without knowing anything just type /models to get the list of the free available ones, and you are done!
But if you want more, this is where many people get stuck, thinking they need to go out and buy expensive subscriptions. You don’t.
Once you are inside the OpenCode TUI, type the following command:
/connect
This will open a menu of different “providers.” A provider is just the company that owns the AI brain. You will see options like Anthropic, OpenAI, and Google.
I highly recommend starting with a free option to get your feet wet. You can use Google’s AI (through their free tier) or even explore the built-in free models offered through OpenCode’s own “Zen” service.
Let’s walk through the Google option as an example:
- Select “Google” from the menu.
- It will likely ask you for an “API Key.”
Now, don’t panic. An API key is just a long, unique password that tells Google, “Hey, it’s me, and I have permission to use this service.” You can get one for free by visiting the Google AI Studio website.
I explained everything in my article about Gemma4
It takes about two minutes. You copy that key, go back to your terminal, paste it in, and hit Enter.
the free models as of June 2026
Once you have entered the key, OpenCode will perform a quick handshake with the provider. If everything is correct, you will see a message saying “Connection successful.”
Congratulations! You have just successfully wired your local agent to a world-class intelligence. You are now officially “online.”
Step 4: Your Very First Command
This is the moment we have all been waiting for. The brain is connected, the body is ready, and it is time to give your first order.
Let’s start with something simple to make sure the “handshake” between your computer and the AI is working perfectly. We will ask it to create a small Python file.
In the OpenCode interface, type:
Create a simple Python script that prints "Hello, OpenCode!" and save it as hello.py
Watch what happens. You will see text appearing on the screen. This isn’t just the AI talking; this is the agent thinking and acting. It will say something like: “I will now create the file hello.py and write the code.”
Then, you will see the file actually appear in your folder.
👉 Tip: Did you noticed that the Agent already run the test itself to see if the app in python was working?
To verify it worked, you can run the script yourself in your terminal:
python hello.py
If you see “Hello, OpenCode!” printed on your screen, you have done it. You have just successfully used an AI agent to perform a real-world task. It sounds small, but this is the foundation of everything that comes next.
👉 Tip: you can execute shell commands without leaving the TUI. The same way you do it in Colab or Jupyter Notebook, start the command with an exclamation mark. The result will be printed in the TUI.
Example from the small GIF above:
!ls
You can see in the GIF above the main commands to know and keyboard shortcuts:
TABto move from Plan to Build mode/to get the list of built-in commandsctrl+pfor the entire list of options
👉 Tip: we are in the Windows Terminal but with a GIT Bash session. If you use Git Bash directly, remember that
CTRL+Vdoes not work to paste text. You need to useSHIFT+INS
Troubleshooting: When Things Don’t Go According to Plan
Even for the pros, things occasionally go sideways. If you run into trouble, don’t worry. Here are the three most common hiccups:
“Command not found”
If you type opencode and your computer says it doesn't know what that is, the installation likely didn't finish or your terminal needs to be "refreshed."
🧰 Try closing your terminal window completely and opening a new one. If that fails, try running the installation command again.
“Connection Error” or “Unauthorized” This almost always means something went wrong with your API key.
🧰 Double-check that you didn’t accidentally copy an extra space at the beginning or end of the key. Also, make sure you actually have a valid key from the provider’s website.
Python or npm errors If you get errors while installing or running scripts, it might be because your computer is missing a fundamental building block.
🧰 Most of the time, simply updating your software (pip install package) or following the specific instructions for your operating system will fix this.
for unknown reasons to me, Gemini thinks that a digital assistant is a woman
Conclusion: You are Now an Agent User
Take a moment to appreciate what you just accomplished. In just a few minutes, you went from having nothing to having a functional, intelligent agent sitting on your machine, ready to assist you.
You have learned how to install software using package managers, how to navigate a terminal interface, how to connect to a cloud-based intelligence, and how to give your first command. These are the building blocks of a much larger journey.
In our next article, we are going to move from “playing around” to “getting serious.” We will talk about AGENTS.md, the secret document that allows you to give your AI agent a permanent memory and a set of specific instructions for your projects.
The revolution is easy to start. The fun part is learning how to lead it. See you in the next one!
I hope you enjoyed the article. If this story provided value and you wish to show a little support, you could:
- Clap a lot of times for this story
- Highlight the parts more relevant to be remembered (it will be easier for you to find them later and for me to write better articles)
- Write with me on this Publication: there is no better way to learn than writing about it!
- Follow my publication https://medium.com/artificial-intel-ligence-playground
If you want to read more, here are some ideas:
메타데이터
- post_id
- bf9d5800f6b3
- slug
- beginner-to-expert-your-first-60-seconds-with-opencode-bf9d5800f6b3
- url
- https://medium.com/artificial-intel-ligence-playground/beginner-to-expert-your-first-60-seconds-with-opencode-bf9d5800f6b3
- canonical_url
- https://medium.com/artificial-intel-ligence-playground/beginner-to-expert-your-first-60-seconds-with-opencode-bf9d5800f6b3
- author_url
- https://medium.com/@fabio.matricardi
- status
- ok
- fetched_at
- 2026-06-16 19:09:56
