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

# Quick start with formae Cloud

> Go from nothing to a managed cloud resource by talking to your coding assistant.

<Warning>
  **The formae MCP plugin has been renamed from `formae-mcp` to `formae`.**
  If you installed `formae-mcp`, uninstall it and install `formae` before continuing.
  Follow the [migration steps](/documentation/guides/ai-coding-assistants#migrate-from-formae-mcp).
</Warning>

With formae Cloud the agent runs for you, so there is no agent to deploy and
nothing to keep running. You install the formae plugin into the coding assistant
you already use, and then you describe what you want.

You will sign in, connect a cloud account, and create a real resource. Every
step is a sentence you say to your assistant. You will not run a formae command
at any point, and you do not need to know that a formae binary exists: your
assistant installs and drives it on your behalf.

<Note>
  Running the agent yourself instead? The
  [Quick start with an AI assistant](/documentation/get-started/quickstart-ai-assistant)
  covers the self-hosted path, where you install formae and start the agent
  locally.
</Note>

<Steps>
  <Step title="Install the assistant plugin">
    <Tabs>
      <Tab title="Claude Code">
        ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
        /plugin marketplace add platform-engineering-labs/formae-marketplace
        /plugin install formae@formae-marketplace
        ```

        Restart Claude Code so it picks the plugin up.
      </Tab>

      <Tab title="Codex">
        ```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
        codex plugin marketplace add platform-engineering-labs/formae-marketplace
        codex plugin add formae@formae-marketplace
        ```
      </Tab>

      <Tab title="Cursor">
        Clone the repository, link the skills, then point Cursor at its
        launcher in `~/.cursor/mcp.json`:

        ```bash theme={"languages":{"custom":["/languages/pkl.json"]}}
        git clone https://github.com/platform-engineering-labs/formae-mcp.git ~/.cursor/formae
        mkdir -p ~/.agents/skills
        ln -s ~/.cursor/formae/skills ~/.agents/skills/formae
        ```

        ```json theme={"languages":{"custom":["/languages/pkl.json"]}}
        {
          "mcpServers": {
            "formae": {
              "command": "/home/you/.cursor/formae/scripts/start-mcp.sh"
            }
          }
        }
        ```

        Use an absolute path.
      </Tab>

      <Tab title="OpenCode">
        Clone the repository, link the skills, then register the server in
        `opencode.json`. See
        [AI coding assistants](/documentation/guides/ai-coding-assistants) for
        the full block.
      </Tab>
    </Tabs>

    This installs the formae MCP and its skills. On first launch it downloads
    the prebuilt pieces it needs to talk to your installation.
  </Step>

  <Step title="Sign in">
    Ask your assistant:

    ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
    set up formae for me
    ```

    It signs you in to formae Cloud. If a browser cannot open where you
    are working, such as in a container or over SSH, it switches to a device
    flow and gives you a verification URL and a code to enter there, which you
    can open on any device that has a browser.

    If you do not have an organization yet, your assistant sends you to
    [console.formae.ai](https://console.formae.ai) to create one and provision an
    agent, then picks the conversation back up. Provisioning takes a few
    minutes.

    When it finishes you have an agent running in formae Cloud and a profile
    pointing at it.
  </Step>

  <Step title="Connect a cloud account, then manage something in it">
    The rest differs by cloud: what you need to hand over, how much access
    formae is granted, and what the smallest real resource looks like. Pick
    yours.

    <Tabs>
      <Tab title="AWS">
        **Connect.** Tell your assistant `connect my AWS account`. It will never
        infer which account: provisioning trust into the wrong one is not a
        mistake a default should be able to make.

        If you have AWS credentials available, it lists your local profiles with
        the account each one resolves to and asks you to pick, so the choice is
        about credentials and the account they reach rather than an id typed from
        memory. It then provisions the trust directly. If you have none, it asks
        for the 12-digit account id and hands you a CloudFormation quick-create
        link; you deploy the stack under your own console session and give it the
        role it produced. Either way no long-lived key is created.

        **Target.** Connecting an account establishes trust and nothing more:
        until a target exists there is nowhere for formae to create or discover
        anything. A [target](/documentation/concepts/target) is *where* resources
        live, and for AWS that is the account paired with a **region**. Your
        assistant asks for a label and a region, then writes and applies the
        declaration.

        **Create something real.**

        ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
        Create an S3 bucket in my-target
        ```

        Bucket names are globally unique across all of AWS, so your assistant
        asks you for one, and anything generic is long gone.
      </Tab>

      <Tab title="GCP">
        **Connect.** Tell your assistant `connect my GCP project`. It asks for
        the project id rather than inferring one from gcloud's active
        configuration, for the same reason it does on AWS. There is no console
        template for GCP, so this is a single step rather than a hand-off and
        back.

        The access granted is broad: editor on the project, plus the ability to
        manage its IAM. Your assistant tells you before anything is created.
        Read it.

        If the agent is running somewhere other than the machine you are sitting
        at, your assistant offers a Google sign-in rather than assuming a browser
        can open where the agent is.

        **Target.** A [target](/documentation/concepts/target) is *where*
        resources live, and for GCP that is the **project** paired with a
        **region**. Your assistant asks for a label and a region, then writes and
        applies the declaration.

        **Create something real.**

        ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
        Create a storage bucket in my-target
        ```

        Two things bite here. Bucket names are globally unique across all of
        Google Cloud. And the location must be a single region such as
        `us-central1`: formae does not accept the multi-region `US` or `EU`
        spellings, and will refuse the declaration rather than create something
        you did not mean.

        If a resource fails with an API-disabled error, that is the Cloud Storage
        API not being enabled on the project. Enable it and ask again.
      </Tab>

      <Tab title="Azure">
        **Connect.** Tell your assistant `connect my Azure subscription`. It asks
        for the subscription id rather than inferring one from az's active
        configuration.

        With `az` credentials available this is a single step. Without them your
        assistant relays the exact `az login` command for you to run, or hands
        you a subscription-scoped ARM template that opens prefilled in the
        portal.

        The access granted is Contributor plus User Access Administrator, which
        together are close to owner. Your assistant tells you before anything is
        created.

        If your account is a guest in another directory, or spans several
        tenants, your assistant will ask for the tenant. Otherwise it is derived
        and you are never asked.

        **Target.** A [target](/documentation/concepts/target) is *where*
        resources live, and for Azure that is the **subscription** alone. Unlike
        AWS and GCP there is no region on an Azure target: location belongs to
        each resource instead.

        **Create something real.**

        ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
        Create a storage account in my-target
        ```

        A storage account lives in a resource group, so your assistant declares
        the group too and formae creates them in order. You asked for the thing
        you wanted; the rest comes along.

        Storage account names are stricter than most: 3 to 24 characters,
        lowercase letters and digits only, no hyphens.
      </Tab>
    </Tabs>

    Whichever cloud you chose, your assistant writes the forma, simulates it so
    you can see what would change, and applies it once you agree. There is no
    command that creates a target, in the same way there is no command that
    creates a bucket. Everything in formae is created by declaring it and
    applying.
  </Step>

  <Step title="See what was already there">
    Discovery has been running against your target since you created it. Ask:

    ```text theme={"languages":{"custom":["/languages/pkl.json"]}}
    What unmanaged resources do you see in my-target?
    ```

    These are resources that existed before formae. They are visible but not
    managed, and you can bring any of them under management by importing them
    into a forma.
  </Step>
</Steps>