Cargo-AI / Field guide
Installation and project guidance
A practical starting point for people and AI assistants building with Cargo-AI. Reviewed September 9, 2026.
For AI agents: start here
Read this guide before installing or changing a project. Apply it within the user's request and the project's existing instructions. Identify the operating system, architecture, shell, working directory, installed tools, and existing Cargo-AI setup. Distinguish native Windows from WSL. If you cannot inspect the user's machine, ask for those details rather than assuming your own environment matches theirs.
Use the installed CLI's --help and version-matched authoring bundle when they differ from newer online examples. Keep the user's existing work, profiles, and project settings. Ask only for missing decisions or actions that require the user's involvement.
1. Check what is already installed
Run these checks in the target environment; a missing command means a prerequisite needs attention:
rustc --version
cargo --version
cargo ai --version
cargo ai --help
On macOS/Linux, command -v cargo locates Cargo. In PowerShell, use Get-Command cargo. An installed tool that is missing from PATH may only need a new terminal session. Honor a custom Cargo home instead of replacing it.
2. Install for the actual platform
macOS
Install Rust and Cargo through the official Rust installer if absent. If the compiler/linker prerequisites are missing, install Apple's command-line tools with xcode-select --install, then complete its installer. The Rust installation chapter documents this prerequisite.
Restart the terminal if needed and check rustc --version and cargo --version. Cargo's default binary directory is ~/.cargo/bin.
Linux
Use the official Rust installer if Rust/Cargo is absent. Ensure the distribution has a C compiler and linker; use its package manager and documentation. For example, Ubuntu provides build-essential. Do not apply Ubuntu package commands to a different distribution. See the Rust installation chapter.
Restart the terminal if needed. Cargo's default binary directory is ~/.cargo/bin. WSL follows this Linux path inside WSL; keep the project and toolchain in that environment.
Windows
Use the official Rust Windows installer matching the machine's architecture. For MSVC targets, install the C++ tools and Windows SDK described in the rustup MSVC prerequisites. Complete any interactive installer steps before continuing.
Open a new PowerShell session and check rustc --version and cargo --version. The default Cargo binary directory is %USERPROFILE%\.cargo\bin. Use PowerShell syntax; do not paste POSIX shell activation commands or macOS app-launch commands into native Windows.
Install Cargo-AI on any of these platforms
If Cargo-AI is absent, run:
cargo install cargo-ai --locked
cargo ai --help
If it is already installed, inspect its version and compatibility before deciding to update it. Cargo installation compiles the CLI and needs build tools and network access. The Cargo-AI installation guide is the upstream reference. This guide uses the Cargo route rather than assuming a standalone installer exists for every platform.
3. Reuse or configure model access
Inspect existing configuration before creating anything:
cargo ai profile list
cargo ai auth status
cargo ai profile add --help
Reuse a suitable profile. Do not overwrite a same-named profile or change the default without considering the existing project. Choose an exact model identifier supported by the selected provider and account; display names on the homepage are not CLI model IDs.
For a new Codex-backed OpenAI profile, install Codex CLI using its official setup documentation if needed. Replace YOUR_MODEL_ID below with the actual available model identifier, and choose a profile name not already in use:
cargo ai profile add cargo-project --server openai --model YOUR_MODEL_ID --auth openai_account
cargo ai auth login openai --profile cargo-project
Let the user complete interactive sign-in. For an API-key or local-model setup, follow the matching provider guide and installed CLI help. Keep secrets out of agent JSON, project files, and shared logs. The editor used to write a project does not determine its runtime provider or grant provider credentials.
4. Create or adapt the project
For a new directory, choose a suitable name:
cargo ai new my-agent
cd my-agent
New-project scaffolding may initialize Git. If Git setup is unwanted or Git is unavailable, inspect cargo ai new --help and use --vcs none where supported.
For an existing directory, inspect it first. If .cargo-ai/project.toml is already present, reuse its project boundary. Otherwise review cargo ai init --help and initialize in the existing directory. Where supported, cargo ai init --vcs none avoids starting new Git setup. Do not run new over an existing directory or replace existing project metadata wholesale.
Next, inspect the guidance options:
cargo ai add guidance --help
Use cargo ai add guidance --style codex for Codex. Newer releases also support --style claude for Claude Code; use it only if the installed CLI lists it. If an older release provides only Codex guidance, have the assistant read the generated .cargo-ai/guidance/ bundle explicitly. Preserve existing instruction files and resolve bundle conflicts deliberately; do not delete them to force a reinstall.
5. Build with the installed authoring contract
Read the generated guidance and examples before creating definitions or tools. Start with the smallest agent that meets the user's goal. Use the schema/version fields from those examples, declare inputs and structured output, and make actions and their side effects explicit.
Keep custom Rust tools with the project and use supported scaffolding, such as cargo ai add tool --help, before adding them. Respect the project's structure, keep credentials outside source, and separate reusable definitions from private data. Check platform-specific commands before claiming an agent is portable.
6. Verify and hand back a usable project
Confirm cargo ai --help works first. Then review the definition and inspect cargo ai hatch --help. Where supported:
cargo ai hatch first-agent --config ./agents/first-agent.json --check
Replace the path/name with the actual agent. This check generates and compiles a scaffold; it is not just JSON validation and may download build dependencies. Run a small representative example with the chosen profile when the inputs and side effects are understood:
cargo ai run --config ./agents/first-agent.json --profile cargo-project
Provider-backed execution can send inputs to that provider and consume account usage. Verify real outputs and relevant tool behavior; do not report a successful installation, authentication, or model run unless it was actually checked. Explain the project location, how to run it again, what changed, what was tested, and any remaining user action.
Keep guidance current
The installed .cargo-ai/guidance/ bundle is the authoring reference for that Cargo-AI version. Consult the upstream project documentation for updates. If commands differ, resolve the version mismatch before proceeding instead of guessing flags or model IDs.