# Getting Started

This guide takes a new project from `keel init` to a running app in your AWS account.

## Prerequisites

- An AWS account
- An IAM access key that can create IAM users, roles, and policies. You use it once during `keel auth setup`.
- Docker (for local builds)
- OpenTofu (auto-downloaded on first use)

**The AWS CLI is not required for the basic workflow**
Keel uses its own project credentials under `~/.keel/contexts/`. It does not read AWS CLI profiles, `~/.aws/credentials`, or the SSO cache, and it removes ambient AWS configuration from OpenTofu subprocesses.

A plain `keel exec` speaks the session protocol itself. Port forwarding (`keel tunnel`, `keel db psql`), `keel run -i`, and `keel exec --legacy-session` do require the AWS CLI and `session-manager-plugin` on your PATH.

`keel auth setup` currently accepts only an access key ID and secret, so you cannot use SSO or other temporary STS credentials for setup. Keep the original IAM access key secure: it is also the recovery path if the first administrator loses their MFA device.

## Install

Coming soon. The Homebrew formula and the source repository are not public yet.

## Your first deploy

```bash
# Initialize a new project (interactive: name, region, networking, port, pipeline)
keel init

# Edit keel.yml to match your app
vim keel.yml

# Set up IAM roles, your Keel admin user, and its MFA device (admin, one-time)
keel auth setup

# Start a session — prompts for a one-time code
keel auth login

# Provision infrastructure
keel up

# Deploy your application
keel deploy

# Check status
keel status

# Launch the interactive dashboard
keel dashboard
```

### What each command did

1. **`keel init`** created `keel.yml` with your app name, region, explicit [networking choices](./what-is-keel#networking-choices), services, and pipeline source. It also created an annotated `keel.yml.example` for options you may add later.
2. **`keel auth setup`** created three least-privilege IAM roles (`keel-admin`, `keel-developer`, and `keel-viewer`), an IAM user that can assume the admin role, and an MFA device for that user. See [The Auth Model](./auth).
3. **`keel auth login`** exchanged your access key and MFA code for an eight-hour STS session.
4. **`keel up`** generated and applied OpenTofu configuration for the VPC, cluster, registry, load balancer, and add-ons.
5. **`keel deploy`** built the image, registered a task-definition revision for each service, ran the `release:` command, and promoted the services.

**Run `keel auth setup --dry-run` first to preview every IAM policy document Keel would create, without touching AWS.**

## Next steps

- [Configuration](./configuration) — everything `keel.yml` can express
- [Deployments](./deployments) — how deploys work, rollback, and the deploy lock
- [Team Onboarding](./teams) — adding teammates with MFA-gated access
- [Deploying Rails](../deploying-rails) — a complete worked example