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

# Quickstart

> Get started locally in minutes

<iframe src="https://www.loom.com/embed/bc30719ec5e54405b71027742f772da2" className="w-full aspect-video rounded-xl" title="YouTube video player" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowFullScreen />

## Installation

<Steps>
  <Step title="Install the soma binary">
    ```bash theme={null}
    curl -sSL https://trysoma.ai/install.sh | sh
    ```
  </Step>

  <Step title="Create a new project">
    The soma init command will create a new project from one of our git templates. Run `soma init` to see all available options.

    <Tabs>
      <Tab title="Typescript / Vercel AI SDK">
        ```bash theme={null}
          soma init --template typescript-ai-sdk  hello-world-agent
          cd hello-world-agent
          # install dependencies. You can use any package manager you want.
          pnpm install
          # start the dev server
          soma dev --clean
        ```
      </Tab>

      <Tab title="Python / Langchain">
        ```bash theme={null}
          soma init --template python-langchain-template  hello-world-agent
          cd hello-world-agent
          # install dependencies. You can use any package manager you want.
          uv sync
          # start the dev server
          soma dev --clean
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure a secret management encryption key">
    <Info>
      Please run all the remaining commands in a separate terminal whilst the dev server is running.
    </Info>

    An encryption key is necessary to keep secrets, MCP credentials and sensitive auth middleware configuration safe.

    <Tabs>
      <Tab title="Local key">
        ```bash theme={null}
          soma enc-key add local --file-name master.bin
        ```

        Local encryption keys will be added to the `.soma/envelope-encryption-keys/$filename` file. Local keys are useful for development and testing. However if you intend to share this project or deploy it, we advise using AWS KMS or storing the local key as a CI secret and injecting it before running soma commads.
        You can migrate your encrypted data between different key types by using the `soma enc-key migrate` command.

        <Warning>
          Never commit the `.soma/envelope-encryption-keys` folder to version control.
        </Warning>
      </Tab>

      <Tab title="AWS KMS">
        ```bash theme={null}
          soma enc-key add aws --arn arn:aws:kms:eu-west-2:xxx:key/xxx --region eu-west-2
        ```

        You will need to ensure your current terminal session has the required AWS environment variables set to access the KMS key. These are normally:

        * `AWS_ACCESS_KEY_ID`,
        * `AWS_SECRET_ACCESS_KEY`,
        * `AWS_SESSION_TOKEN` or,
        * `AWS_PROFILE`
      </Tab>
    </Tabs>
  </Step>

  <Step title="Set up environment variables">
    ```bash theme={null}
      soma secret set OPENAI_API_KEY xxx
    ```

    Our example agent uses OpenAI to generate responses.
  </Step>

  <Step title="Explore Soma, debug your agent">
    <Tabs>
      <Tab title="via UI">
        Open your browser to [http://localhost:3000](http://localhost:3000).
        Navigate to the "**Agent 2 Agent**" > "**Chat**".
        Send a message to your agent and wait for the response.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Configure MCP functions">
    <Tabs>
      <Tab title="via UI">
        Open your browser to [http://localhost:3000](http://localhost:3000).
        Navigate to the "**Bridge MCP functions**" > "**Enable functions**".

        From here, you can see a list of pre-build Bridge MCP functions, mainly for integrating with third-party SaaS providers. Additionally, you should also see any provider from your project's functions folder which you can now configure and enable.
      </Tab>
    </Tabs>
  </Step>
</Steps>

## Next steps

<Columns cols={2}>
  <Card title="The anatomy of a Soma project" icon="rocket" href="/next-steps">
    Learn about our file based project structure and configuration options
  </Card>

  <Card title="Enable secure MCP functions" icon="rocket" href="/next-steps">
    Learn about enabling secure MCP functions for your agent
  </Card>

  <Card title="Common agent patterns" icon="rocket" href="/next-steps">
    How to build chat, workflow or a combination of both agents
  </Card>
</Columns>