Getting Started

Get AMOF running and your first multi-repo workspace bootstrapped in under 5 minutes.

Prerequisites

Tool	Required	Purpose
Python 3.10+	Yes	AMOF CLI and orchestrator
Git 2.30+	Yes	Worktree support
Docker	For local clusters	k3d provisioner
Terraform	For cloud provisioners	AWS, GCP, Azure, DO, Hetzner
kubectl	For Kubernetes ops	Cluster interaction
Helm 3	For chart deployments	Kubernetes package management

Optional but recommended: Cursor or VS Code with the Dev Containers extension, and an LLM API key (Anthropic, OpenAI, or OpenRouter).

amof check

Installation

Option 1: DevContainer (Recommended)

The DevContainer includes all tools pre-installed. The container mounts ~/.aws and ~/.ssh automatically for credential access.

git clone https://github.com/your-org/amof.git
cd amof

Open in Cursor or VS Code and click "Reopen in Container" when prompted.

Option 2: Local Installation

git clone https://github.com/your-org/amof.git
cd amof

# Install Python dependencies
pip install -r requirements.txt

# Add the amof alias to your shell
source scripts/amof-aliases.sh

# Verify installation
amof check

Configure Your Environment

Create a .env file in the project root with your API keys and credentials:

.env

# LLM Provider (pick one or more)
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...

# Git credentials (for private repos)
GIT_TOKEN=ghp_...

# Optional: Jira / Confluence
ATLASSIAN_USER=your.email@company.com
ATLASSIAN_TOKEN=...

Set your default ecosystem in .amof/agent.yaml:

.amof/agent.yaml

default_ecosystem: my-project

Quickstart: Local Development with k3d

The fastest way to experience AMOF -- no cloud credentials needed.

1. List Available Ecosystems

amof ecosystem list

2. Bootstrap a Workspace

amof -e supabase-platform install

This creates a Git worktree at worktrees/supabase-platform/, clones all repositories defined in the manifest, generates repo profiles, and builds the codebase index.

3. Check Status

amof -e supabase-platform status

Output

REPO                   BRANCH              COMMIT   MODE  STATUS
supabase-kubernetes    workspace/supa...   a1b2c3d  RW    OK
supabase-config        workspace/supa...   e4f5g6h  RW    OK
shared-infra           main                i7j8k9l  RO    OK

4. Spin Up Local Infrastructure

amof -e supabase-platform spin deploy

This creates a local k3d Kubernetes cluster with load balancer ports mapped to your host.

5. Start Working on a Feature

# Create feature branches in all writable repos
amof ticket start add-auth-flow

# Check the new branches
amof status

6. Run the AI Agent

# Interactive mode
amof agent

# Single-shot task
amof agent "Add a healthcheck endpoint to the backend service"

# Read-only analysis
amof agent --plan "Explain the authentication flow across all repos"

7. Push and Clean Up

# Push all branches to remotes
amof push

# When finished, archive the workspace
amof archive -m "Auth flow complete"

# Tear down infrastructure
amof -e supabase-platform spin destroy

Quickstart: Cloud Deployment with AWS

# 1. Bootstrap
amof -e aws-boilerplate install

# 2. Configure Terraform Variables
# Create ecosystems/aws-boilerplate/spin.tfvars

# 3. Deploy Cloud Infrastructure
export AWS_ACCESS_KEY_ID="..."
export AWS_SECRET_ACCESS_KEY="..."
amof -e aws-boilerplate spin deploy

# 4. Work, Push, Destroy
amof ticket start feature-login
amof agent "Implement OAuth2 login in the frontend"
amof push
amof -e aws-boilerplate spin destroy

Using the Control Plane UI

AMOF includes a web-based control plane for visual management.

amof server start

This launches the Backend API at http://localhost:8000 (Swagger at /docs) and the Frontend UI at http://localhost:3000 (Next.js dashboard).

Ecosystem Grid -- See all ecosystems with status, agent count, and last indexed time
Orchestrator Log -- Real-time SSE-streamed terminal output with ANSI colors
Agent Chat -- Interactive AI chat with ask/plan/execute modes
Task Runs -- Monitor active and completed agent runs
Release Management -- Bump versions, promote pre-releases, view audit log

What's Next?

Topic	Link
Understand the system design	Architecture
Configure ecosystems and provisioners	Ecosystems & Provisioning
Master the AI agent system	AI Orchestration
Explore the API and UI	Control Plane
Learn every CLI command	CLI Reference
Configure AMOF	Configuration