Set up OpenCode

This guide configures the Versalist command-line interface (CLI). It also configures the Model Context Protocol (MCP) when OpenCode supports it.

Requirements

• Node.js 18 or later
• npm
• An account or provider credential for OpenCode
• A Versalist account
• A Versalist application programming interface (API) key with the required scopes

1. Install OpenCode

curl -fsSL https://opencode.ai/install | bash

• The installer supports macOS and Linux.
• Use the provider guide if your model provider needs an environment variable.

2. Authenticate OpenCode

Authenticate OpenCode with its account or model provider. This credential is separate from your Versalist key.

opencode auth login
opencode auth list

1. Select a model provider when OpenCode asks for one.
2. Complete the provider authentication flow.
3. OpenCode stores provider credentials in its local authentication file.

3. Create a Versalist key

If you are already signed in, open API key settings. Create one key for this agent.

1. Name the key for OpenCode and its environment.
2. Select only the scopes that your workflow requires.
3. Copy the key before you close the dialog.
4. Store the key in a password manager or secret manager.
5. Load the key into the agent process environment.

The agent-aware key page selects all three scopes for the full workflow.

• Use read:challenges to browse or start challenges.
• Use submit:solutions to submit a solution.
• Use read:submissions to read submission history through MCP.

Remove a scope if your workflow does not use it.

export VERSALIST_API_KEY=vk_live_...
test -n "$VERSALIST_API_KEY" && echo "Versalist API key is set"

4. Install the Versalist CLI

npm install -g @versalist/cli
versalist --help

Use npx -y @versalist/cli if you do not want a global installation.

5. Connect Versalist

Add the Versalist MCP server to opencode.json. Keep the key out of project files.

opencode mcp add

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "versalist": {
      "type": "local",
      "command": ["npx", "-y", "@versalist/cli", "mcp"],
      "enabled": true,
      "environment": {
        "VERSALIST_API_KEY": "{env:VERSALIST_API_KEY}"
      }
    }
  }
}

• The interactive command adds an MCP server.
• The project file keeps the Versalist server configuration with the repository.
• The environment reference keeps the key out of the project file.

6. Launch OpenCode

Open the project directory in a trusted terminal. Then start the agent.

opencode

7. Run the Versalist workflow

versalist list --search "agentic code optimization"
versalist start agentic-code-optimization-review

versalist run --command "python agent.py" --label baseline
versalist evaluate --run <baseline-run-id> --command "pytest" --score 70

versalist run --command "python agent.py" --label candidate
versalist evaluate --run <candidate-run-id> --command "pytest" --score 84

versalist compare --baseline <baseline-run-id> --candidate <candidate-run-id>
versalist submit --url https://github.com/you/solution --title "Candidate run"

The versalist start command loads challenge files. It does not launch the coding agent.

The example python agent.py command is a placeholder. Replace it with your agent command.

Verify the setup

Use these read-only checks before you start a challenge.

opencode --version
opencode auth list
opencode mcp list

Confirm that the host reports the Versalist server or command. Do not run a write tool only to test the connection.

Limitations

• OpenCode provider authentication does not authenticate the Versalist command-line interface.
• OpenCode exposes Versalist tools only while the local MCP server is active.
• The CLI stores local run evidence under .versalist/.
• The CLI does not upload local evidence automatically.
• The submit command sends metadata and URLs, not .versalist/ contents.

Revoke access

1. Open API key settings.
2. Find the key by name and last-use time.
3. Revoke the Versalist key.
4. Delete the versalist entry from opencode.json.
5. Run the logout command if you must remove the model provider session.
6. Remove VERSALIST_API_KEY from the process environment.
7. Restart the agent process.

opencode auth logout

Revoke the provider credential separately if it is exposed. A Versalist key revoke does not revoke the provider credential.

Official documentation

Use these official sources if the vendor changes a command or setting.

• OpenCode documentation
• OpenCode providers
• OpenCode configuration
• OpenCode MCP servers

Return to the coding agent index, or open the Versalist CLI reference.

Canonical guide: /docs/coding-agents/opencode