← Back to all topics
00 · Getting Started

Initial Setup

Two steps to get up and running: request your GitHub Copilot licence, then download and connect OpenCode.

Step 1 — Get a GitHub Copilot licence

OpenCode uses GitHub Copilot as its AI model provider. You need an active licence before you can connect — there are two ways to get one:

If you're using OpenCode at work:

  1. Check whether your organisation already has a Copilot Business or Enterprise subscription — ask IT, your manager, or check internal docs
  2. If yes, request a seat through your usual software request process
  3. Once granted, the licence is activated on your work GitHub account

If you're using OpenCode personally:

  1. Go to github.com/features/copilot
  2. Click Get Copilot and choose the Individual plan (free trial available)
  3. Sign in with your personal GitHub account and complete checkout
Already have a licence? Skip to Step 2. To check, go to github.com/settings/copilot — if Copilot is active it will show there.

Step 2 — Download OpenCode

Go to opencode.ai/download and download the OpenCode Desktop app for your system:

Not sure which Mac you have? Click the Apple menu → About This Mac. If it says "Apple M1" (or M2, M3, M4) choose Apple Silicon. If it says "Intel" choose Intel.

Desktop vs Terminal: The download page also shows terminal install options (Homebrew, npm, etc). These are fine if you're comfortable in the terminal, but the Desktop app is the easiest starting point and works the same way.

Step 3 — Open OpenCode

There are two ways to use OpenCode — pick whichever feels right for you. Both do the same thing.

Option A: OpenCode Desktop app (recommended if you're new)

Just open it like any other app on your Mac or Windows machine. It installs to your Applications folder and launches with a clean interface. No terminal needed.

Option B: Terminal (macOS)

Some people prefer to run OpenCode directly from the Mac Terminal — it gives you a bit more control and is worth trying once you're comfortable. To do this:

  1. Open Terminal (search for it in Spotlight with Cmd+Space)
  2. Navigate to your working folder — e.g. cd ~/Desktop/OpenCode
  3. Type opencode and hit Enter
Not sure which to use? Start with the Desktop app. You can always switch to Terminal later — the experience is similar, but more user friendly in app to start with.

Step 4 — Connect GitHub Copilot

When you open OpenCode for the first time you need to connect it to your Copilot licence.

In the Desktop app:

  1. Open OpenCode Desktop
  2. Go to Settings → Providers
  3. Find GitHub Copilot and click Connect
  4. OpenCode will show you a short code and a URL — go to github.com/login/device and enter the code
  5. Sign in with your GitHub account and authorise
  6. GitHub Copilot will now appear as connected — you can select your model from the model toggle at the bottom of the screen

In the Terminal:

  1. Type /connect and hit Enter
  2. Search for and select GitHub Copilot
  3. Go to github.com/login/device and enter the code shown
  4. Sign in with your GitHub account and authorise
  5. Run /models to confirm it's connected and select a model

Step 5 — Start your first session

OpenCode works from a folder on your computer — everything in that folder becomes available as context for your session.

  1. Create a folder for your OpenCode work — e.g. a folder on your Desktop called OpenCode
  2. Open OpenCode and navigate to that folder, or open the folder first and launch OpenCode from there
  3. Type /init — this analyses the folder and sets up OpenCode for it
  4. Ask it something — you're ready to go
Useful things to know from day one:

Ctrl+P — open the command palette (shows everything OpenCode can do)
/models — switch AI model
/undo — revert the last change OpenCode made
/share — generate a shareable link to your current conversation

Where your settings live

OpenCode reads its settings from two places: a global file that applies to everything you do, and an optional project file inside a specific folder that only applies when you're working in that folder.

Global settings live in:

~/.config/opencode/opencode.jsonc  (Mac & Linux)
%USERPROFILE%\.config\opencode\opencode.jsonc  (Windows)

This is where things like your connected tools (MCPs), your default permissions, and any plugins you install are kept. New sessions inherit these settings automatically — you don't need to set them up again per project.

Project settings (optional) live in:

<your project folder>/.opencode/opencode.jsonc

If a project folder has its own config file, OpenCode reads the global one and then the project one — project settings override or extend global ones where they overlap. Most people don't need a project config at all; it's only useful if a specific project needs different tools or rules.

You don't need to edit these files by hand. You can ask OpenCode to do it for you in any session. For example: "Add the GitHub MCP server to my global config" or "Update my opencode.jsonc to allow access to my Documents folder". OpenCode will edit the file safely and tell you what it changed.
Restart after config changes. If you (or OpenCode) edit either config file, quit and reopen OpenCode for the changes to take effect. The current session keeps the old settings until you restart.

One useful habit: have a dedicated session or project (some people use one called "Assistant" or "Setup") for asking OpenCode about itself — config changes, plugin questions, "how does X work". Keep your actual work sessions focused on the work.

What's next