Install and Bootstrap

Deploying IAS into a repository is called bootstrapping. The bootstrap process adds the IAS scaffold -- documentation structure, agent configs, CLI tooling, and optionally the hybrid runner -- to your target repository. After bootstrap, agents can operate on the repo with full context and tooling.

Quick start

The fastest way to deploy IAS is with the guided install command:

ias install /path/to/repo

This interactive flow walks you through profile selection, handles Git operations (branch creation, commit, push), and can optionally open a pull request for team review.

What bootstrap does

Bootstrap copies a structured set of files into your repository that enable IAS to operate:

1. Documentation scaffold -- The docs/ias/ directory with templates for project context, decisions, runs, and knowledge gaps.
2. Agent configuration -- AGENTS.md, CLAUDE.md, and tool-specific config directories (.claude/, .codex/skills/) that teach AI agents how to work in your repo.
3. Local CLI -- The scripts/ias helper for preflight checks, creating runs, and other local operations.
4. Hybrid runner (optional) -- The scripts/ias-runner/ automated execution engine for work tasks and PR reviews.

The scope of what gets installed depends on the profile you choose.

Bootstrap profiles

Choose a profile based on how you plan to run agents:

• The default profile for ias install (interactive) is control-plane.
• The default profile for ias bootstrap (non-interactive) is terminal.

The bootstrap command

Interactive install (recommended)

ias install /path/to/repo

The interactive installer prompts you for:

• Profile selection
• Whether to create a branch, commit, push, and open a PR
• Whether to stash uncommitted changes (if any)

Non-interactive bootstrap

For scripted or CI deployments, use the bootstrap command directly with explicit flags:

ias bootstrap /path/to/repo --profile control-plane

Common options

Example with all Git operations enabled:

ias install /path/to/repo --commit true --push true --pr true --pr-base main

What gets created

After bootstrap, your repository will contain the following structure (paths vary by profile):

Documentation scaffold (docs/ias/)

Agent configuration

Tooling

Git integration

Bootstrap is designed to work cleanly with your existing Git workflow:

• IAS stages and commits only IAS-owned paths. It does not run git add -A on your entire repo.
• If the target repo has uncommitted tracked changes, the installer will offer to stash them (interactive mode) or fail with a clear error (non-interactive mode).
• The default branch name for the bootstrap commit is ias/bootstrap. Customize it with --branch <name>.
• You can customize the PR base branch with --pr-base <branch>.

Console-driven bootstrap

You can also trigger bootstrap from the Console UI:

1. Open the repo in Repositories.
2. Click Bootstrap IAS.
3. A local agent will create the scaffold and optionally open a PR.
4. If PR-based, merge the PR and use the Verify install action to confirm IAS is present on the default branch.

The Console needs to verify that the bootstrap exists on the repo's default branch before it can run Build Context or Context Architect jobs.

Force mode (upgrading)

If IAS is already installed in the repository, run bootstrap again with --force to update framework files:

ias install /path/to/repo --force

Force mode preserves your project-specific artifacts -- it only overwrites generic framework files:

This makes --force safe for upgrading IAS in a repository that already has project context populated.

Local-only mode

For sensitive or client codebases where IAS framework files should not appear in Git history:

ias install /path/to/repo --local-only

Local-only mode appends .gitignore rules that separate framework files from project artifacts:

This means:

• Each developer on the team must bootstrap locally to get the runtime files.
• Project decisions, context, and run history are shared through Git as usual.
• Your agent framework IP does not land in the client's Git history.

The hybrid runner stores operational telemetry under docs/ias/runs/<run>/runner/ (prompts, event logs, job artifacts). In local-only mode, this telemetry is gitignored by default. You can opt in to tracking it if needed.

After bootstrap

Once IAS is deployed, the next step is to populate your project context so agents understand your codebase.

Via the Console (recommended)

1. Link the repo: ias repo link /path/to/repo
2. Start the agent: ias agent start
3. In the Console, navigate to the repo and click Build Context.
4. Provide the base goal, hard constraints, and optionally configure research tools (MCP).
5. A local agent writes the context docs and optionally opens a PR.

Manually

1. Edit docs/ias/project-context.md with your project metadata:
   • Whether the system is in production
   • Deployed version reference (if any)
   • Sensitive data classification
   • Non-negotiable constraints
   • Stakeholders and success criteria
2. Populate docs/ias/context/base-goal.md with the high-level objective.
3. Add relevant references to docs/ias/context/inputs.md (tickets, PRDs, architecture docs).
4. Run preflight to verify everything is ready: ias preflight

Troubleshooting

Next step: Configure agents to start processing tasks against your bootstrapped repo.