Verified release checks — v0.4.5
| Check | Recorded result |
|---|---|
| Core CI | Passed on Linux, macOS and Windows, including packaged-source installation and installed CLI smoke |
| Package Qualification | Source canary and enrolled official package passed on all three platforms |
| Security | Audit and separate dependency policy checks passed on the released source |
| Full Product Qualification | Passed; OpenAI, Anthropic, Gemini, xAI and Jev live checks passed; Mistral remains unverified after rate limiting |
| Jev | Eight live Choice/Score journey cases passed using requested/returned jev-1.13.0, within the GitHub provider aggregate; eight requests, no retry |
| Registry Installation | Passed on Linux, macOS and Windows; verified the published v0.4.5 crate and exact source |
These checks describe published source fd48374 and bounded scenarios. Registry Installation ran from workflow revision 94e0611 while explicitly verifying that published source; its badge uses that workflow revision. See release evidence for source identities, provider limitations and historical results.
Release notes · Documentation at v0.4.5 · Release testing
Development status: 
Build declarative AI agents. Ship them as local CLI apps.
Cargo AI is an open-source Rust harness builder for auditable AI workflows. Define inputs, structured output, actions, and tool connections in readable JSON; run the definition directly; or hatch it into a native executable you can inspect and keep.
cargo ai run --config ./agent.json
cargo ai hatch my-agent --config ./agent.json- Readable by design: one JSON definition makes inputs, output, and side effects reviewable and diffable.
- Run or hatch: iterate through the Cargo AI runtime, then export a native CLI executable from the same definition.
- Real workflow building blocks: use text, URLs, images, files, conditions, local commands, tools, email, image generation, speech generation, transcription, and child agents where supported.
- Provider choice: connect to OpenAI, Anthropic, Gemini, xAI, Mistral, TypeSafe Jev, or a local Ollama server using compatible schemas and inputs.
- Project and package workflows: assemble agents, Rust tools, and assets into inspectable local or hosted packages with explicit permission boundaries.
- Portable and auditable: target macOS, Linux, and Windows while keeping generated source and shipped behavior visible.
This path creates one local agent, runs it, validates it, and hatches it. A Cargo AI account is not required.
Install Rust and Cargo using the official Rust installation guide, then install Cargo AI:
cargo install cargo-ai
cargo ai --helpSee Install Cargo AI for platform and PATH details.
If your ChatGPT plan includes Codex, you can reuse that subscription-backed sign-in without creating an API key. ChatGPT Plus currently includes Codex in the CLI; access and limits can vary by plan and workspace. Install Codex CLI first. See OpenAI authentication and Codex pricing and plan access. Verified: 2026-08-30.
cargo ai profile add openai-account \
--server openai \
--model gpt-5.6-terra \
--auth openai_account
cargo ai auth login openai --profile openai-account --set-defaultThe Cargo AI login command starts Codex's browser sign-in, verifies the resulting local session, and associates it with the profile.
If that model is not available to your plan, choose another current model exposed by your Codex account. Direct OpenAI API keys and every alternative provider are documented under Model providers.
Development builds containing account discovery can list exact model choices
with cargo ai models list --profile openai-account, or use
cargo ai models list --server openai --auth openai_account with an existing
Codex login before creating a profile. Listing does not start login or prove
inference access. See account discovery boundaries.
Builds advertising models thinking can query exact choices with
cargo ai models thinking --profile openai-account --model MODEL_ID --output-format json.
--thinking on and --thinking off select qualified Boolean controls, case-insensitively.
Use --thinking-choice VALUE for a literal exact name such as on; unavailable settings use provider default with an explanation.
Save a choice with cargo ai profile set openai-account --thinking VALUE, or override
one run with cargo ai run ./agent.json --profile openai-account --thinking VALUE.
An unavailable choice uses provider default with an explicit explanation.
See thinking selection and inheritance
for explicit default, clearing, action overrides and rebuild requirements.
{
"agent_definition_schema_version": "2026-09-09.r1",
"inputs": [
{
"type": "text",
"text": "What is 2 + 2? Return the answer as an integer."
}
],
"agent_schema": {
"type": "object",
"properties": {
"answer": {
"type": "integer",
"description": "The result of the math problem."
}
}
},
"actions": [
{
"name": "show_answer",
"logic": { "==": [{ "var": "answer" }, 4] },
"run": [
{
"platform": ["macos", "linux"],
"kind": "exec",
"program": "printf",
"args": ["The answer is 4.\\n"]
},
{
"platform": "windows",
"kind": "exec",
"program": "cmd",
"args": ["/C", "echo", "The answer is 4."]
}
]
}
]
}agent_definition_schema_version identifies the Cargo AI definition contract, not the agent, package, or product version. Copy it from a current Cargo AI template or guidance bundle rather than inventing one.
cargo ai run --config ./agent.json --profile openai-accountCargo AI resolves the inputs, requests the declared structured result, validates it locally, and runs matching actions only after validation succeeds.
cargo ai hatch first-agent --config ./agent.json --check
cargo ai hatch first-agent --config ./agent.json
./first-agentOn Windows, run .\first-agent.exe in PowerShell or first-agent.exe in Command Prompt. The longer getting-started guide explains the same workflow and its next steps.
A Cargo AI definition has four main parts:
inputs— optional ordered text, URL, image, or file content for the model.runtime_vars— optional typed values supplied by the caller to control logic or selected step settings without editing JSON.agent_schema— the structured result Cargo AI requests and validates.actions— conditional follow-up work composed from orderedrunsteps.
Runtime flags can replace, append, or prepend model inputs. Named inputs and runtime variables make reusable workflows explicit. Actions can run sequentially or in parallel while each action keeps its own steps ordered. Child-agent inputs and runtime values are forwarded deliberately; parent and child output objects are not silently merged.
Read Agent definitions and Actions and child agents for the human guides. The version-matched offline contract installed for coding assistants remains under templates/guidance/.
| Area | Current surface |
|---|---|
| Inputs | Ordered text, URL, image, and file inputs; named bindings and runtime overrides |
| Structured output | Typed JSON schema with scalar fields and a bounded structured-data lane for tools |
| Actions | Local commands, Cargo AI tools, child agents, email, image generation, speech generation, and transcription |
| Control flow | JSON Logic, per-step conditions, failure policies, platform selectors, and sequential/parallel action scheduling |
| Runtime | Direct interpreted execution or generated native executables |
| Projects | Explicit build profiles, project-local Rust tools, assets, and runtime defaults |
| Packages | Local and hosted install, version management, exported entrypoints, permissions, and persistent data |
| Observability | Deterministic terminal status, automatic local usage history and optional NDJSON export |
Provider capabilities differ. Unsupported input or action combinations fail explicitly instead of silently dropping data or falling back to another provider.
| Provider | Connection |
|---|---|
| OpenAI | ChatGPT/Codex account session or direct API key |
| Anthropic | Native Messages API with an Anthropic API key |
| Google Gemini | Native Interactions API with a Gemini API key |
| xAI | Responses API with an xAI API key |
| TypeSafe Jev | Text/URL-text Choice and explicit rubric Score through an API-key profile |
| Mistral | Chat Completions API with a Mistral API key |
| Ollama | Locally operated OpenAI-compatible server |
TypeSafe Jev support is introduced in 0.4.2 for local and hatched Choice/Score workflows; see release status for publication availability. New rubric definitions opt into 2026-09-19.r1; hosted storage of that revision is deferred. Ordinary scaffolds retain 2026-09-09.r1. See TypeSafe setup for the complete limits and profile-aware hatch checks.
The provider overview compares current input, image, speech, and transcription boundaries. Model availability belongs to each provider or account; Cargo AI does not maintain a model allowlist or certify every model/schema combination.
Bootstrap a project and install version-matched AI authoring guidance:
cargo ai new my-agent-project
cd my-agent-project
cargo ai add guidance --style codexUse --style claude for Claude Code, or repeat --style to install both discovery entrypoints. The installed .cargo-ai/guidance/ bundle is self-contained and is the authoritative offline authoring contract for that Cargo AI version.
Use cargo ai guidance status for a read-only ownership/version check and cargo ai guidance update for an explicit offline update from the installed binary. User-owned instructions are preserved. See guided setup and guidance maintenance.
Projects can add local Rust tools, explicit build profiles, package metadata, assets, and runtime defaults. Start with Projects and local tools, then use Packages when the workflow should be installed, versioned, or shared.
Local run, hatch, build, and package workflows do not require a Cargo AI account. Register only when you want account-backed definition storage, public handles, email workflows, or hosted package publishing.
See Accounts and sharing. Account-agent management stays under cargo ai agents; account-backed execution and hatching use the top-level cargo ai run and cargo ai hatch commands.
- Documentation home
- Getting started
- Install and Cargo AI Home
- Model providers
- Agent definitions
- Actions and child agents
- Projects and local tools
- Packages
- Accounts and sharing
- Troubleshooting
- Testing and Product Qualification
- Versioning and release notes
Runnable repository examples include adder_test.json and weather_test.json.
The release history collects changes and upgrade guidance by version. 0.4.5 is the latest verified release, adding usage attribution by environment, package, location, agent and consuming workspace. It preserves the speech/image, transcription and declaration-inspection capabilities and limitations from 0.4.4. See release status and verification for the published source and native installation evidence.
Cargo AI remains under active development. The top release badges describe the named checks attached to the released version; current develop status is labeled separately. Automatic Development CI provides focused feedback. On-demand Product Qualification combines full native Core CI, package lifecycles, required/enrolled hosted providers and security into one fail-closed summary. Each family is also independently runnable; see Testing and Product Qualification.
Scheduling is not built into Cargo AI today. Use an operating-system scheduler such as cron or Windows Task Scheduler when a local agent must run on a schedule.
MIT. See LICENSE.