Skip to content

start-here.mdx

Latest commit

 

History

History
132 lines (98 loc) · 5.47 KB

start-here.mdx

File metadata and controls

132 lines (98 loc) · 5.47 KB
Raw
title Start here
sidebarTitle Start here
description Paste one prompt into your coding agent and let it install the Ravion agent skill and CLI, connect your AWS account, and deploy your project to your own AWS account.
og:image https://www.ravion.com/og/docs/start-here.png
twitter:image https://www.ravion.com/og/docs/start-here.png

Ravion runs infrastructure in your own AWS account, and your coding agent drives it. Setup is one prompt.

Paste this into Claude Code, Cursor, Codex, or any other agent that supports Agent Skills:

Deploy this project to AWS with Ravion. If the use-ravion skill is not installed yet, install it first with `npx skills add ravionhq/skills`, then follow it.

The agent installs the skill if it is missing, then installs the CLI, signs you in, connects your AWS account, writes the project config, applies it, and sets up a build and deploy pipeline. See Ravion agent skill for the plugin and URL install options.

What the agent needs from you

The agent handles the terminal work. Three things need you, because only you can do them:

  • Approve the sign-in. ravion login prints a URL and a short code for you to confirm in the browser. No account yet? Sign up first — Ravion is free for individuals, and teams start with a free trial.
  • Confirm the AWS account. The agent runs aws sts get-caller-identity and asks whether that is the account Ravion should manage. It then connects it by deploying Ravion's CloudFormation stack, which creates a cross-account IAM role. Without AWS CLI credentials, connect it in AWS accounts instead.
  • Connect your Git repository. ravion git connect prints a URL that needs your Git permissions. Skip it if Ravion only deploys images from a registry.

The agent also asks for the decisions it should not guess, such as region, instance sizes, and domains, and it pauses for your approval before any change that modifies, replaces, or removes existing infrastructure.

Working without the skill

Agents that fetch URLs but do not support skills read the hosted copy:

Deploy this project with Ravion: https://www.ravion.com/SKILL.md

To search the docs from the agent's context window, add the Ravion Docs MCP server — the skill installs it on its own, so this is only for doing it up front:

npx add-mcp https://www.ravion.com/docs/mcp --name ravion-docs
Nothing here is required when an agent does the setup for you.

Install the CLI with Homebrew on macOS:

brew install ravionhq/tap/ravion

Or with the install script:

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

Sign in, then select your active organization if you belong to more than one:

ravion login
ravion switch

See Install the Ravion CLI and Authentication.

Confirm which account your credentials belong to: 
aws sts get-caller-identity

Create the Ravion AWS account record and get the CloudFormation template for it:

ravion aws account create --given-id my-account --name "My account" --json
ravion aws account cloudformation-template-url <aws-account-id> --json

Deploy the template in us-east-1, where the template's authenticator runs. The role it creates lets Ravion provision in any region:

aws cloudformation create-stack \
  --region us-east-1 \
  --stack-name ravion-<aws-account-id> \
  --template-url "<templateUrl>" \
  --capabilities CAPABILITY_NAMED_IAM

aws cloudformation wait stack-create-complete \
  --region us-east-1 \
  --stack-name ravion-<aws-account-id>

The template carries your account id and a single-use token, so pass no --parameters and keep the URL private. CAPABILITY_NAMED_IAM is required because the stack creates a named role and named managed policies.

Confirm the connection:

ravion aws account get <aws-account-id> --json

The status field reads CONNECTED once the stack finishes. When Ravion later ships new permissions, review them with ravion aws account policy-diff <aws-account-id>, then apply them with aws cloudformation update-stack and a freshly fetched template URL.

Useful references

Install the skill that teaches agents how to use Ravion. Define environments and module instances from one file. Define build, deploy, trigger, and approval workflows. Understand module definitions, versions, inputs, and config. Browse every Ravion CLI command. File bugs and feedback from the terminal, including from agent sessions.