How to use trae-agent: install, configure and run tasks

What you need before installing Trae Agent

Trae Agent requires Python 3.12 or newer and UV, the Python package manager, which is linked from the project README at docs.astral.sh/uv. You also need an API key for your chosen model provider, or a local Ollama setup. Docker is only needed if you plan to use Docker mode.

• Python 3.12+
• UV (https://docs.astral.sh/uv/)
• An API key for your chosen model provider, or a local Ollama setup
• Docker (only for Docker mode)

Install Trae Agent from source

The README installs Trae Agent by cloning the repository and syncing dependencies with UV. Run these commands in order from your terminal, then activate the virtual environment so the trae-cli command is available.

Configure a model provider with trae_config.yaml

The README recommends YAML configuration. Copy the example file to trae_config.yaml, then edit it with your credentials and preferences. The config file is ignored by git so your API keys stay out of version control. Under model_providers you define each provider and its api_key, and under models you choose which provider and model name the agent uses.

If your provider needs a custom endpoint, add a base_url field after provider. The README notes that only spaces are allowed for indentation in this file, and tabs are not permitted.

Configuration priority is: command-line arguments, then the configuration file, then environment variables, then defaults.

• Copy trae_config.yaml.example to trae_config.yaml
• Set api_key and provider under model_providers
• Set model_provider, model and token settings under models
• Keep trae_config.yaml out of git because it holds your keys

Use environment variables instead of a YAML file

If you prefer not to store keys in a file, the README shows environment variables for each supported provider, including OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY and DOUBAO_API_KEY. Each has a matching _BASE_URL variable. The README mentions storing these in a .env file as an option.

Run your first task and check the configuration

Use trae-cli run with a plain-language task in quotes. Before running real work, you can confirm your setup with show-config. To start a conversational session instead, use interactive mode. Pass --working-dir to point the agent at a specific project folder, and --trajectory-file to save a log of its actions for review.

• trae-cli show-config checks the configuration
• trae-cli run "task" runs a single task
• trae-cli interactive opens a session where you type tasks and use status, help, clear and exit or quit
• --working-dir sets the project folder
• --trajectory-file saves the execution record

Switch providers, including local Ollama models

You can override the provider and model per run with --provider and --model. The README lists examples for OpenAI, Anthropic, Google Gemini, OpenRouter, Doubao and Ollama. For Ollama, the model is a local model name such as qwen3, so you need a working local Ollama setup first.

Trae Agent also supports optional MCP services. The README shows a Playwright example under an mcp_servers section in the YAML file.

• OpenAI: --provider openai --model gpt-4o
• Anthropic: --provider anthropic --model claude-sonnet-4-20250514
• Google Gemini: --provider google --model gemini-2.5-flash
• Ollama: --provider ollama --model qwen3

Run tasks in Docker mode

Docker mode runs tasks in a container. The README says you must make sure Docker is configured in your environment first. You can name a base image, attach to an existing container by ID, or build from a Dockerfile. Note that --working-dir cannot be combined with --docker-container-id.

By default the container is kept after the task; set --docker-keep false to remove it.

• --docker-image runs in a new container from an image
• --dockerfile-path builds an environment from a Dockerfile
• --docker-container-id attaches to an existing container
• --docker-image-file loads a local tar archive image