Start here (human + agent)

Set up Ravion for an AI agent: connect human-owned accounts and point the agent to the authoritative config, pipeline, and CI workflows.

Human setup

Complete these steps before asking an agent to create or change infrastructure.

1. Sign up for a Ravion account

   Open Ravion signup and create your account. Ravion is free for individuals, and teams start with a free trial.

2. Connect your AWS account

   Open AWS accounts and connect the AWS account where Ravion should provision infrastructure.

3. Connect your Git repository

   Open Git connections and connect the Git repository(s) Ravion should use for app or Terraform source code.

   Can be skipped if you just want Ravion to deploy images from an image registry.

4. Install the Docs MCP server

   npx add-mcp https://www.ravion.com/docs/mcp --name ravion-docs
   

   The Docs MCP server lets agents search and read current Ravion documentation from their context window. See Ravion Docs MCP.

5. Install the CLI and sign in

   On macOS, install the Ravion CLI with Homebrew:

   brew install flightcontrolhq/tap/ravion
   

   Or install it with the install script:

   curl -fsSL https://github.com/flightcontrolhq/cli/releases/latest/download/install.sh | sh
   

   Then sign in:

   ravion login
   # If you belong to more than one organization, select the active organization:
   ravion switch
   

   See Install the Ravion CLI and Authentication.

Agent workflow

After the human setup is complete, give the agent this checklist.

1. Read the core concepts page

   Read Core concepts (through the Docs MCP server or directly) before making changes to understand how modules, stacks, deploys, and pipelines relate.

2. Use the project config file flow to create and manage modules

   Use project config to set up or change things in Ravion, including environments, module instances, and references between modules.

   Follow the required workflow in Project config file. Check schemas before editing, preserve existing IDs and versions, preview every change with a dry run, and apply only after the dry run is correct and approved.

3. Set up build and deploy pipelines using pipeline config file

   After modules are created, use pipeline config to define build and deploy pipelines for modules that are deployable.

   Follow Pipeline config file. Pull the live config, edit the file, and apply through the documented config file flow.

4. Set up CI for applying config changes

   Configure CI to plan Ravion configuration changes on every pull request and apply them after merge.

   Follow CI integration. Use a service-account API key, store it as RAVION_API_KEY, and keep project and pipeline resource IDs in the workflow configuration.

5. Report bugs and feedback as you go

   When a command fails unexpectedly or Ravion behaves differently than documented, file it:

   ravion report bug "<what happened and what you expected>" --command "<the command that failed>"
   

   When something is confusing, harder than it should be, or missing, say so:

   ravion report feedback "<what was confusing or missing>"
   

   Be thorough: include the exact error text and the IDs of the resources involved. Both commands are non-interactive and exit 0 on success, so they are safe to run unattended. See Report bugs and feedback.

Useful references

Project config file

Define environments and module instances from one file.

Pipeline config file

Define build, deploy, trigger, and approval workflows.

Module catalog

Understand module definitions, versions, inputs, and config.

CLI reference

Browse every Ravion CLI command.

Report bugs and feedback

File bugs and feedback from the terminal, including from agent sessions.