## The short version

A deployment agent is a coding agent that can carry an application from local source to a live release using a deployment tool with machine-readable commands and results. With Ample, the agent can inspect the repo, resolve a plan, deploy services and data resources, read logs, and reuse the same workflow for later changes.

## WHO THIS IS FOR

This guide is for builders evaluating how AI coding agents can handle deployment work while keeping the source and infrastructure plan visible.

## How to do it

1.  **Give the agent a scoped setup path**  
    The Ample homepage creates a one-use onboarding secret and a snippet that installs the CLI, authenticates it, and establishes Ample as the repo's deploy tool.

2.  **Plan from repository evidence**  
    The agent runs Ample's repo inspection. Open questions include evidence, options, a safe default, and a named answer path.  
    ```
    ample plan
    ```

3.  **Record the infrastructure contract**  
    Writing ample.toml makes services, databases, volumes, links, domains, and non-secret configuration reviewable in the repo.  
    ```
    ample plan --write
    ```

4.  **Apply and diagnose**  
    The agent runs the synchronous deploy once, reads the final result, and uses build or runtime logs if the release fails.  
    ```
    ample up
    ```

5.  **Reuse the workflow**  
    On later changes, the agent uses the existing plan and content-addressed deploy behavior instead of inventing a new release process.

## What this supports

### Good fit

- Stable JSON output and exit codes
- Evidence-backed planning questions
- Version-matched agent documentation
- Scoped tokens and budget controls

### Know the limits

- The agent still acts with the permissions granted to its token
- Missing secret values require a human or external secret source
- Deployment automation does not make untested application code correct

## Common failure modes

### The agent polls a synchronous deploy

Run the deploy once and read its live, failed, or blocked result.

### The agent guesses through a plan question

Use the supplied evidence, options, safe default, and answer path.

### The agent commits a secret

Declare the key as secret and pass its value with encrypted environment input.