Connect Aider to AvalAI

Aider is a terminal pair-programming tool that can discuss and edit selected files. Connect it directly to AvalAI through its OpenAI-compatible provider. Begin in ask mode, with automatic commits disabled and no repository map, then explicitly choose when to edit.

Source-reviewed on 2026-09-08 using Aider's official endpoint and CLI documentation. No live AvalAI/Aider session was run.

1. Install Aider

The official installer creates a separate Python environment for Aider. Follow the installation guide, including its supported Python/platform requirements:

python3 -m pip install aider-install
aider-install
aider --version

Record the installed version for team rollout. Run the first session in a disposable project with a harmless README.md, not a company repository containing secrets.

2. Store the endpoint and key privately

Create a private configuration directory:

mkdir -p "$HOME/.config/aider"

Using your editor, create ~/.config/aider/avalai.env with the following content. Replace only the key placeholder with a dedicated AvalAI key. Do not commit this file or paste the real key into a shell command.

OPENAI_API_BASE=https://api.avalai.ir/v1
OPENAI_API_KEY=replace-with-your-avalai-key

chmod 600 "$HOME/.config/aider/avalai.env"

Aider's documented variable is OPENAI_API_BASE, not OPENAI_BASE_URL. If your shell already exports OPENAI_API_BASE or OPENAI_API_KEY for another service, unset those in this session before using the file; do not assume which credential source wins.

3. Start a discussion-only session

From the disposable project's directory, run:

aider --env-file "$HOME/.config/aider/avalai.env" \
  --model openai/gpt-5.4-mini \
  --weak-model openai/gpt-5.4-mini \
  --chat-mode ask --map-tokens 0 \
  --no-auto-commits --no-dirty-commits README.md

Important distinctions:

• openai/ selects Aider/LiteLLM's OpenAI-compatible adapter. The AvalAI model ID is gpt-5.4-mini; do not send the Aider prefix directly to AvalAI.
• The main and weak model are explicit. Other modes, such as architect/editor, can introduce another model; configure those separately.
• --chat-mode ask is for discussion without automatic edits. It is not a filesystem or network sandbox.
• --map-tokens 0 disables the repository map for this first narrow test.
• --no-auto-commits --no-dirty-commits prevents Aider from automatically committing generated or pre-existing changes.

The current AvalAI catalog lists this model for Chat Completions. Aider compatibility also depends on its model metadata and edit format; an accepted HTTP request alone does not prove editing quality.

4. Verify the first request

Ask:

Summarize the purpose of README.md in one sentence.
Do not edit files, run commands, or suggest installing anything.

Check that the answer matches the file and that no source change occurred. In a Git project, inspect:

git status --short
git diff

Aider can create local configuration/history files even in a discussion workflow. Protect .aider* files and exclude private history from source control. Inspect existing .aider.conf.yml and project instructions before trusting a repository; command-line options are not a complete security boundary.

When you are ready for edits, use the bounded coding exercise, explicitly switch to code mode, review the diff, and run the tests yourself. Do not enable --yes-always for the pilot.

Troubleshooting

Symptom	Next check
Requests go to the wrong service	Check OPENAI_API_BASE, inherited environment variables and the selected env file.
401 / 403	Dedicated AvalAI key, account access, accidental whitespace; never print the env file in diagnostics.
Model not found	Use openai/gpt-5.4-mini in Aider, with the exact AvalAI ID after the prefix.
Unknown context/cost warning	Read model warnings; do not silence warnings or invent metadata. Check AvalAI's catalog and pricing.
Chat works but edits fail	Editing format and model ability are separate from API compatibility. Try one small file and inspect the proposed diff.
Large usage	Reduce attached files and history; keep the repository map off initially. Check AvalAI usage, not just local price estimates.
Audio or image feature fails	Those are separate capability paths. A chat endpoint does not configure transcription or media generation.

Official sources and next steps

• Aider repository.
• OpenAI-compatible APIs, installation, and CLI options.
• Model catalog, pricing, rate limits, and coding-agent exercise.

No installer was run, credential stored, edit applied, or paid request made during this source review. Validate your exact Aider version and model on non-sensitive files before team use.