Zed setup | Versalist Documentation

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

Launch command

zed .

Start Zed in the project directory.

Project configuration

.zed/settings.json

Review this file before you trust the project.

Versalist connection

MCP and CLI

The agent can start the local Versalist MCP server.

Requirements

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

1. Install Zed

shell

brew install --cask zed

This command installs Zed with Homebrew on macOS.
In Zed, run cli: install cli binary from the command palette.
Use the official installation guide for Linux or a direct download.

2. Authenticate Zed

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

Open Zed.
Sign in to Zed with GitHub if your account requires it.
Open Settings, then AI, then LLM Providers.
Add the model provider credential that Zed requires.
Zed stores provider keys in the system keychain.

3. Create a Versalist key

Create a key for Zed

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

Name the key for Zed and its environment.
Select only the scopes that your workflow requires.
Copy the key before you close the dialog.
Store the key in a password manager or secret manager.
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.

Load and check the Versalist key

Replace the placeholder with a value from your approved secret store.

shell

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

Do not commit a key

Do not put a Versalist key in source code, a project setting, a log, or a shared command.

4. Install the Versalist CLI

shell

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 Zed user settings file. Keep the key out of project files.

Zed MCP configuration

json

{
  "context_servers": {
    "versalist": {
      "command": "npx",
      "args": ["-y", "@versalist/cli", "mcp"],
      "env": {
        "VERSALIST_API_KEY": "<VERSALIST_API_KEY>"
      }
    }
  }
}

Open Settings, then AI, then MCP Servers to add the local server.
Zed does not document environment interpolation for this setting.
Put the key only in the user settings file.
Do not put a key in .zed/settings.json or source control.

6. Launch Zed

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

Before you run this command, run cli: install cli binary from the Zed command palette.

shell

zed .

7. Run the Versalist workflow

Select a challenge

List published challenges and load one challenge into the repository.

Record a baseline

Run the current implementation and evaluate its recorded run.

Record a candidate

Run the changed implementation and evaluate its recorded run.

Compare and submit

Compare both evaluations. Submit the project web address when the evidence is ready.

Shared Versalist workflow

Replace the example commands, run identifiers, score values, and project web address.

shell

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.

check

zed --version

Open Settings > AI > MCP Servers and confirm that versalist shows Server is active.

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

Limitations

Zed requires project trust before an agent can use project tools.
Zed does not document environment interpolation in context server settings.
The .zed/settings.json file must not contain a Versalist key.
MCP tool availability can differ by the active Zed Agent profile.
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

Open API key settings.
Find the key by name and last-use time.
Revoke the Versalist key.
Open Settings, then AI, then MCP Servers.
Remove the versalist server.
Delete the key value from the Zed user settings file.
Sign out from the Zed account menu if you must remove the Zed session.
Remove VERSALIST_API_KEY from the process environment.
Restart the agent process.

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.

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