Sharing Team Configurations

In previous lessons, we learned how to customize OpenCode for your personal workflow, control its permissions, and recover from errors. You now have a robust environment that works perfectly for you. However, most software development happens in teams, and this introduces a new challenge: consistency.

If every developer on your team uses a different AI model or has different permission settings, the code generated by OpenCode might vary wildly from person to person. To solve this, we need to share our configuration so that everyone is on the same page.

But there is a catch — we must share the rules (like which model to use) without sharing our secrets (like API keys). In this final lesson, we will learn the industry-standard pattern for separating public project configuration from private credentials. By the end, you will be able to set up a repository that any new team member can clone and use immediately, keeping your project secure and consistent.

The opencode.json file is designed to be the single source of truth for how OpenCode behaves in a specific project. Because it defines the standard operating procedure for the project, it should be committed to your version control system (like Git). This ensures that when a teammate clones your repository, they automatically get the correct settings without having to ask you for them.

However, not everything belongs in this file. You should only include fields that are valid OpenCode configuration options that apply to everyone — specifically, the model and permission fields. These define "what tool we use" and "how cautious we should be."

Here is an example of a safe, shareable opencode.json file:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-haiku-4-5",
  "permission": {
    "read": "allow",
    "write": "ask",
    "edit": "ask",
    "bash": "ask"
  }
}

In this example, the team has agreed to use anthropic/claude-haiku-4-5 to keep costs low and responses fast. They have also agreed that the agent needs permission to write code or run commands (ask) but can read files freely (allow). Because this file contains no sensitive data, it is perfectly safe to share with the entire team.

You might be tempted to add your API key directly to the opencode.json file so that everything is in one place. This is a security risk. API keys are effectively passwords that are tied to your personal identity and billing information. They are not valid configuration fields for opencode.json, and OpenCode is designed to look for them elsewhere: in environment variables.

Environment variables are dynamic values that exist in your computer's operating system rather than in a specific file inside your project. This keeps them isolated from your project code. To make managing these variables easier, developers often use a local file named .env.

A standard .env file looks like this:

ANTHROPIC_API_KEY=sk-ant-your-secret-key-here

To load these variables into your current session so OpenCode can use them, you run a command to read the file and export the variables. This keeps the key in memory for the session but keeps it out of your project's configuration history.

export $(cat .env | xargs)

Creating a separate .env file is only the first step. If you accidentally commit this file to Git, you have just shared your secret key with the world. To prevent this, we must explicitly tell Git to ignore the file. This is done using a special file called .gitignore.

The .gitignore file contains a list of file names or patterns that Git should never track. Adding your credentials file to this list is a "day-one" task — it should be one of the first things you do when setting up a new project.

Here is how you configure it:

1. Create or open .gitignore.
2. Add the line .env.
3. Save the file.

Once this is done, you can verify that Git is ignoring your secrets by running git status. Even if you have created a .env file, it should not appear in the list of files waiting to be committed.

# Create the .env file
echo "ANTHROPIC_API_KEY=sk-demo-key" > .env

# Check status
git status

Output:

On branch main
Untracked files:
  (use "git add <file>..." to include in what will be committed)
    opencode.json
    .gitignore

nothing added to commit but untracked files present

Notice that .env is missing from the list. This confirms that your secrets are safe, while your opencode.json and .gitignore are ready to be shared.

Now that we understand the components, let's look at the complete pattern for a healthy team repository. The goal is to have a structure where configuration is shared, but credentials are local.

1. The Shared Repository (Committed)

These files exist in Git and are downloaded by everyone:

• opencode.json: Contains the model and permission settings.
• .gitignore: Lists .env to prevent accidents.

2. The Local Environment (Ignored)

These files exist only on your computer:

• .env: Contains ANTHROPIC_API_KEY (or other provider keys).

When you are ready to push your team setup, your commit command should look like this:

git add opencode.json .gitignore
git commit -m "Add team OpenCode configuration"

By strictly separating these two concerns, you ensure that your project is portable. Anyone can work on it, provided they have their own API key, without needing to edit the project's source code to change settings.

The true test of this setup occurs when a new developer joins the team. Because you have set up the project correctly, their onboarding process is smooth and requires no guesswork. They do not need to ask you "which model are we using?" or "what permissions should I set?" because those answers are already in the repository.

Here is the workflow for a new team member:

1. Clone the repository: They download the code and the opencode.json config.
2. Create credentials: They create their own .env file with their personal key.
3. Load credentials: They export their key into the shell.
4. Run OpenCode: The tool starts immediately.

git clone https://github.com/org/project.git
cd project

# New member supplies their own key
echo "ANTHROPIC_API_KEY=sk-ant-new-member-key" > .env
export $(cat .env | xargs)

# Start coding
opencode

OpenCode automatically combines the model and permission settings from the shared file with the authentication from the environment variable. The new member is ready to code in seconds, using the exact same standards as the rest of the team.

Mistakes happen. Sometimes, a developer might paste an API key directly into opencode.json and commit it before realizing their error. If this happens, it is crucial to act quickly to secure the project.

First, invalidate the compromised key. Go to your API provider's dashboard (e.g., Anthropic or OpenAI) and revoke the key immediately. Once a key is committed to Git history, it should be considered public and dangerous.

Next, fix the code to follow the correct pattern:

1. Open opencode.json and delete the line containing the API key.
2. Create a .env file and paste your new API key there.
3. Ensure .env is listed in your .gitignore.
4. Commit the changes to clean up the repository.

# 1. Edit opencode.json to remove the key
# 2. Add .env to .gitignore

git add opencode.json .gitignore
git commit -m "Remove API key from config; use environment variable"

While this removes the key from the current version of the code, remember that the old key still exists in the Git history. This is why rotating the key (creating a new one and deleting the old one) is the most important step in this process.

In this course, we have traveled from setting up your first project to managing complex team workflows. We learned how to define project standards with opencode.json, control agent autonomy with permission, recover from errors using undo/new, and finally, share configurations securely across a team.

In this final lesson, we established the Golden Rule of OpenCode configuration: Commit the behavior (model, permission), but ignore the credentials (API keys). By using opencode.json for settings and environment variables for keys, you create a development environment that is both consistent for your team and secure for your organization.

Now it is time to put this into practice. In the upcoming exercises, you will simulate a team setup scenario. You will create a shared configuration, mistakenly commit a credential (on purpose!), and then practice the workflow to fix it and secure the repository properly. Congratulations on mastering OpenCode customization — you are now ready to build faster and smarter!