Installation

Rig ships as the rig crate on crates.io. This page covers adding it to a project, the prerequisites you need, provider API keys, and optional cargo features. Once you’re set up, head to the Quickstart to build your first agent.

Prerequisites

• Rust toolchain — install it via rustup. Rig targets a recent stable Rust; keeping your toolchain up to date with rustup update avoids most build issues.
• A provider API key — Rig calls hosted models by default. For the examples in these docs you’ll need an OpenAI key exposed as the OPENAI_API_KEY environment variable. Other providers use their own variables (for example ANTHROPIC_API_KEY, COHERE_API_KEY, GEMINI_API_KEY).

Add Rig to your project

From inside a Cargo project, add rig and Tokio:

cargo add rig tokio

rig is Rig itself. Tokio is the async runtime Rig runs on. Because most examples use #[tokio::main], enable Tokio’s macros and rt-multi-thread features (or just full):

cargo add tokio --features macros,rt-multi-thread

Set your API key

Rig clients created with from_env() read credentials from environment variables. Export your key before running:

export OPENAI_API_KEY="sk-..."

Caution

Never commit API keys to source control. Use environment variables or a secrets manager, and add local .env files to .gitignore.

Cargo features

rig keeps its default footprint small and gates optional functionality behind cargo features. Depending on what you build, you may enable features for things like:

• derive — derive macros for embeddings and structured extraction.
• Multimodal support — features for image and audio content in completions.
• Provider- or transport-specific capabilities layered on top of the core API.

Enable a feature when adding the crate:

cargo add rig --features derive

The authoritative, versioned list of feature flags and what each enables lives on docs.rs/rig — check there for the set that matches the version you depend on.

Companion crates

Vector store integrations and other backends live in separate companion crates so you only pull in what you use. For example:

• rig-mongodb — MongoDB vector store
• rig-lancedb — LanceDB vector store
• rig-neo4j — Neo4j vector store
• rig-qdrant — Qdrant vector store
• rig-surrealdb — SurrealDB vector store

Add one alongside rig when you need it:

cargo add rig rig-lancedb

See Integrations for the full list of providers and stores.

Next steps

• Quickstart — build and run your first agent.
• Core Concepts — the mental model behind Rig.
• API reference on docs.rs — exhaustive signatures and features.