Skip to content

OPENCODE_SETUP.md

Latest commit

 

History

History
94 lines (68 loc) · 3.29 KB

OPENCODE_SETUP.md

File metadata and controls

94 lines (68 loc) · 3.29 KB
Raw

opencode Setup for Cortex / Snowflake

ML-workflow tasks run with --repo-mode use the opencode CLI for multi-file repo edits via understand_repo and edit_repo. opencode talks to an LLM provider directly (it doesn't go through clients/cortex.py), so it needs its own credentials.

Why this is non-trivial on Cortex

opencode's built-in anthropic provider expects:

  • The Anthropic-style header x-api-key: <key>.
  • Standard upstream model IDs (e.g. claude-sonnet-4-5-20250929).

Snowflake Cortex's Anthropic-compatible endpoint expects:

  • Authorization: Bearer <token> (Cortex PAT).
  • Renamed model IDs (e.g. claude-sonnet-4-6).

Neither side natively understands the other. The fix below configures opencode to send Bearer auth and to know about Cortex's renamed models, while pointing its baseURL at the Cortex endpoint.

One-time setup

  1. Make sure your .env is sourced in the shell (so ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN are exported).

  2. Run the helper that generates ~/.config/opencode/opencode.json:

    bash scripts/setup_opencode.sh

    This writes a global opencode config that:

    • Points anthropic provider's baseURL at ${ANTHROPIC_BASE_URL}/v1.
    • Sets Authorization: Bearer ${ANTHROPIC_AUTH_TOKEN} via the headers option.
    • Registers Cortex's renamed model IDs (claude-sonnet-4-6, claude-opus-4-7, claude-haiku-4-5) under the anthropic provider.

  3. Verify it works:

    ./opencode/opencode run "say hi" \
    -m anthropic/claude-sonnet-4-6 --format json | tail -3

    You should see a step_finish event with a non-zero token count and no error.

Running a repo_mode task

Once the global config is in place, repo_mode tasks work like other ml_workflow tasks:

CUDA_VISIBLE_DEVICES=0 python3 run.py \
    --task nanogpt \
    --repo-mode \
    --agent-model-id claude-sonnet-4-6 \
    --branch-tag <tag> \
    --max-agent-turns 1000 \
    --enable-search-review \
    --exp-name <name>

The agent's tool surface will swap edit_train_file → edit_repo and get_current_code → understand_repo, both backed by core/opencode.py which shells out to the opencode CLI.

Failure modes seen during initial setup

  • ProviderModelNotFoundError: opencode rejects the model name. Fix: ensure the model ID is registered under provider.anthropic.models in ~/.config/opencode/opencode.json.

  • 401 Unauthorized (Cortex): Bearer token missing or expired. Fix: refresh ANTHROPIC_AUTH_TOKEN in .env, re-run scripts/setup_opencode.sh.

  • 404 Not Found on /messages: baseURL is missing the /v1 suffix. The Cortex endpoint is at ${ANTHROPIC_BASE_URL}/v1/messages, so the configured baseURL must end in /v1.

  • 403 AccessDenied with bedrock:InvokeModelWithResponseStream: opencode is hitting AWS Bedrock instead of Cortex. Check that _PROVIDER_TO_OPENCODE in core/opencode.py maps cortex → anthropic, and that the global config exists.

Token rotation

The Cortex PAT is embedded in ~/.config/opencode/opencode.json. To rotate:

  1. Update ANTHROPIC_AUTH_TOKEN in .env.
  2. Re-run scripts/setup_opencode.sh (it overwrites the global config).

Don't commit ~/.config/opencode/opencode.json to git — it contains the secret.