> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudthinker.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Register, connect AWS, verify the connection, and run your first AI-powered cost analysis — with a clear success state for every step.

This quickstart takes you from zero to a real result you can verify: a list of your idle EC2 instances with projected monthly savings, returned by an AI agent reading your actual AWS account. Allow **\~10 minutes**, mostly spent waiting for AWS to grant model access and CloudThinker to inventory your resources.

<Info>
  **What you'll need:** an email address, an AWS account with admin (or sufficient IAM) permissions to create a role, and a few minutes to read what the agent returns.
</Info>

***

## The 30-second syntax

Talk to agents in plain language. The full pattern is:

```text theme={null}
@agent #tool your request
```

* **`@agent`** — who does the work: `@alex` (cloud), `@oliver` (security), `@tony` (database), `@kai` (Kubernetes), `@anna` (coordination).
* **`#tool`** *(optional)* — the output you want: `#dashboard`, `#report`, `#recommend`, `#alert`, `#chart`, `#kb`.
* **Your request** — what you need, in your own words. Add any context inline.

See the [CloudThinker Language reference](/guide/language) for the full syntax.

***

<Steps>
  <Step title="Register">
    Sign up at [app.cloudthinker.io](https://app.cloudthinker.io/auth/register).

    1. Enter name, work email, and password
    2. Click the verification link in your inbox
    3. Confirm your profile

    **Success state:** You land in your personal organization with a default workspace ready. The left sidebar shows **New chat**, **Skills**, and **Artifacts** at the top, and an empty conversation panel on the right.

    <Tip>
      Free 14-day trial — no charge until day 15. See [Pricing](/guide/billing/pricing) for plan limits.
    </Tip>
  </Step>

  <Step title="Connect AWS">
    Go to **Settings → Connections → New Connection → AWS**, then pick an authentication method:

    | Method                       | When to use it                                  | Required                                                  |
    | ---------------------------- | ----------------------------------------------- | --------------------------------------------------------- |
    | **IAM Role** *(recommended)* | Production accounts; safer than long-lived keys | Trust policy + permission policy on a role you create     |
    | **Access Key**               | Quick demo or sandbox account                   | IAM user with programmatic access; access key ID + secret |

    For the IAM Role path, CloudThinker shows you the **External ID** to paste into the trust policy and the [minimum permissions](/guide/connections/aws#required-permissions) to attach. The full AWS Console walkthrough — with CloudShell commands and trust-policy JSON — is in the [AWS connection guide](/guide/connections/aws).

    **Safe by default:** the recommended starter policy is read-only. Write actions (rightsizing, instance termination, security-group changes) require a separate policy *and* run under your [approval workflow](/guide/approval) — no agent ever pushes a change without your sign-off on the first runs.

    **Success state:** the connection card flips to **Connected** with a green dot. Discovery starts automatically; within \~2 minutes you'll see a non-zero resource count (instances, RDS, S3, etc.) on the card. If discovery stays at zero, jump to [Troubleshooting](#troubleshooting) below.
  </Step>

  <Step title="Verify discovery">
    Open the **Infrastructure** tab in the left sidebar.

    You should see:

    * A list of regions with non-zero resource counts
    * At least one of: EC2 instances, S3 buckets, RDS databases, Lambda functions
    * A topology view (click the graph icon) showing service relationships

    **Success state:** The resource count matches roughly what you expect for the account. If you connected a sandbox with five EC2s and you see five — you're done. If you see zero or your numbers look wrong, see [Troubleshooting](#troubleshooting).
  </Step>

  <Step title="Run your first prompt">
    Click **New chat** and paste:

    ```text theme={null}
    @alex give me a summary of my AWS resources — count by service, top regions, and any obviously idle instances
    ```

    Alex queries CloudWatch utilization metrics, joins them with the resource inventory, and returns a structured summary.

    **Expected output:** a response within \~30 seconds containing:

    * **Resource counts** — EC2, RDS, S3, Lambda, etc. by region
    * **Idle candidates** — instances with sustained `<20%` CPU over the last 30 days
    * **Projected savings** — monthly dollars at risk if you keep paying for idle resources
    * **Inline reasoning** — *"I checked CloudWatch's `CPUUtilization` metric for the last 30 days and filtered instances where the 95th percentile stayed below 20%"*

    You can drill into any line: click an instance to see its tags, region, owner, and the full metric history Alex consulted.
  </Step>

  <Step title="Try a tool command">
    For richer output shapes, prefix the prompt with a `#tool`:

    ```text theme={null}
    @alex #dashboard EC2 cost breakdown by instance type over the last 30 days
    ```

    Alex returns an interactive dashboard (charts you can sort/filter) instead of a text answer.

    Other tools worth trying once you're connected:

    ```text theme={null}
    @alex #recommend right-sizing options for the over-provisioned instances above
    @alex #report monthly AWS cost narrative I can share with finance
    ```

    **Success state:** the dashboard renders inline; recommendations include both the change and the projected monthly delta.
  </Step>
</Steps>

***

## You're done when…

* [x] You can see your AWS resource count in the Infrastructure tab and it matches reality
* [x] `@alex` returned a summary that named specific instances or services you recognize
* [x] You can explain to a teammate what Alex did to find the idle resources (read the inline reasoning back)

If all three are true, you've completed the first-success flow.

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="AWS connection stays in 'Pending' or 'Failed'" icon="circle-exclamation">
    **Likely cause:** trust policy missing the External ID, or the role's permission policy is too narrow.

    **Check:**

    1. In the AWS Console → IAM → Roles → your role → Trust relationships, confirm the `sts:ExternalId` condition exactly matches what CloudThinker showed you (no extra whitespace).
    2. The role's permission policy includes at minimum `ec2:Describe*`, `rds:Describe*`, `s3:List*`, `cloudwatch:GetMetricStatistics`. Full list: [AWS connection minimum permissions](/guide/connections/aws#required-permissions).
    3. The role's max-session-duration is ≥ 1 hour.

    **Fix:** correct the trust policy / permissions, then click **Reconnect** on the connection card. Discovery restarts automatically.
  </Accordion>

  <Accordion title="Connected, but the resource count stays at zero" icon="magnifying-glass">
    **Likely cause:** the role can be assumed but lacks `Describe` permissions on the regions/services your account actually uses, or the account is in a region you haven't enabled.

    **Check:**

    * Go to **Connection details → Discovery log**. Each region attempted shows its result. `AccessDenied` errors tell you exactly which API call was rejected.
    * Confirm the account actually has resources in at least one region the role can see.

    **Fix:** widen the permission policy to cover the failing API, or enable the relevant region under the connection's region scope.
  </Accordion>

  <Accordion title="Alex says 'I don't have access to AWS yet'" icon="user-slash">
    **Likely cause:** the connection isn't bound to the current workspace. Each connection lives in one workspace; you might be chatting in a different one.

    **Fix:** confirm the workspace selector (top of sidebar) shows the same workspace where you added AWS. Switch workspaces, or re-add the connection in the workspace you're chatting in.
  </Accordion>

  <Accordion title="The first prompt returns generic best practices instead of my actual data" icon="comment-slash">
    **Likely cause:** Alex couldn't reach a tool (CloudWatch, Cost Explorer) — usually a permission gap. Generic answers are the fallback when concrete data isn't available.

    **Check:** scroll to the bottom of Alex's reply; the **Tools used** section lists every API call attempted, with success/failure. Failed calls show the AWS error.

    **Fix:** add the missing permission to the role (CloudWatch read for utilization, Cost Explorer read for spend), reconnect, then retry the prompt.
  </Accordion>

  <Accordion title="Slow response or timeout on the first prompt" icon="hourglass-half">
    **Likely cause:** initial discovery still running — Alex is waiting for the inventory to finish before reasoning over it. Subsequent prompts are much faster.

    **Fix:** wait until the Infrastructure tab shows non-zero resource counts, then re-run the prompt. Discovery typically completes in 2–5 minutes for an account with under 500 resources.
  </Accordion>
</AccordionGroup>

***

## Next steps

<CardGroup cols={2}>
  <Card title="AgenticOps quick wins by role" icon="comments" href="/guide/tutorial/agenticops">
    Find your role, copy a prompt, get a real result in under a minute
  </Card>

  <Card title="Connect more tools" icon="plug" href="/guide/connections/overview">
    Bring in Datadog, GitHub, Kubernetes, Postgres, Slack — agents activate as connections appear
  </Card>

  <Card title="Invite your team" icon="user-plus" href="/guide/workspace-users">
    Add teammates with Owner, Admin, Developer, or Viewer roles and assign workspace access
  </Card>

  <Card title="Upgrade your plan" icon="credit-card" href="/guide/billing/subscription">
    Add seats and move up from the trial when your team is ready — per-seat billing, upgrade any time
  </Card>
</CardGroup>