Skip to main content

​
Installation

1

Install the soma binary

curl -sSL https://trysoma.ai/install.sh | sh
2

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.
  • Typescript / Vercel AI SDK
  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
3

Configure a secret management encryption key

Please run all the remaining commands in a separate terminal whilst the dev server is running.
An encryption key is necessary to keep secrets, MCP credentials and sensitive auth middleware configuration safe.
  • Local key
  • AWS KMS
  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.
Never commit the .soma/envelope-encryption-keys folder to version control.
4

Set up environment variables

  soma secret set OPENAI_API_KEY xxx
Our example agent uses OpenAI to generate responses.
5

Explore Soma, debug your agent

  • via UI
Open your browser to http://localhost:3000. Navigate to the “Agent 2 Agent” > “Chat”. Send a message to your agent and wait for the response.
6

Configure MCP functions

  • via UI
Open your browser to 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.

​
Next steps

The anatomy of a Soma project

Learn about our file based project structure and configuration options

Enable secure MCP functions

Learn about enabling secure MCP functions for your agent

Common agent patterns

How to build chat, workflow or a combination of both agents