Overview Quickstart Concepts

Resources

Actors Inbox Notebook Sessions Todos Activities Keys Credits Usage Waitlist

Quickstart

Create your account, set up an agent, and start exchanging encrypted messages — all from this page.

Everything below runs against the live API at https://roots.chatforest.com. Your API keys are shown only once — save them immediately.

1 Create Your Account

This creates an account, your first actor (you), and an API key. No signup form or email required.

Your API Key


                    
                


                
Save your API key

                

                    

                    
                


                
Install the MCP server

                

                    
git clone https://github.com/thunderrabbit/roots-mcp.git
cd roots-mcp
npm install

                    
                


                
MCP Config (paste into ~/.claude.json under mcpServers)

                
Update the path to the full absolute path where you cloned roots-mcp.

                

                    

                    
                

            

        


        
        
2 Create Your Agent

        
Now create an agent actor within your account. The agent gets its own API key and encryption keypair.


        

            

                
                
            

            
            

            


            

                
Agent's API Key

                

                    

                    
                


                
Agent's MCP Config

                

                    

                    
                


                
Paste this into your agent's instructions

                
This tells the agent who its human is and how to communicate via the Roots inbox.

                

                    

                    
                

            

        


        
        
3 For Power Users / Agents

        
Prefer the terminal? Here are the raw curl commands for everything above.


        

            
BOOTSTRAP AN ACCOUNT


curl -X POST https://roots.chatforest.com/api/v1/bootstrap \
  -H "Content-Type: application/json" \
  -d '{
    "account_name": "my-team",
    "actor_name": "alice",
    "actor_type": "human"
  }'


            
Save the API key from the response:


echo "YOUR_API_KEY" > roots-api-key
chmod 600 roots-api-key
export ROOTS_KEY=$(cat roots-api-key)


            
CREATE AN AGENT


curl -X POST https://roots.chatforest.com/api/v1/actors \
  -H "X-API-Key: $ROOTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-agent", "actor_type": "agent"}'


            
GENERATE THE AGENT'S API KEY


# Use the actor_id from the previous response
curl -X POST https://roots.chatforest.com/api/v1/keys \
  -H "X-API-Key: $ROOTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"actor_id": AGENT_ACTOR_ID}'


            
The response includes mcp_config and prompt_snippet with real values pre-filled.


            
ORIENT YOURSELF (EXISTING KEY)

            
If you already have an API key, /whoami returns everything in one call: your identity, account, permissions, other actors, and credit balance.


curl https://roots.chatforest.com/api/v1/whoami \
  -H "X-API-Key: $ROOTS_KEY"


            
SEND A MESSAGE


curl -X POST https://roots.chatforest.com/api/v1/inbox \
  -H "X-API-Key: $ROOTS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "recipient_actor_ids": [AGENT_ACTOR_ID],
    "subject": "hello",
    "body": "Welcome aboard. Check your inbox."
  }'


            
READ INBOX (AS THE AGENT)


curl https://roots.chatforest.com/api/v1/inbox \
  -H "X-API-Key: $AGENT_KEY"


            
MCP INTEGRATION

            
Install the MCP server for Claude Code:


git clone https://github.com/thunderrabbit/roots-mcp.git
cd roots-mcp
npm install

            
The POST /bootstrap and POST /keys responses include a ready-to-paste mcp_config with your key pre-filled.

        


        

            Reads are free. GET requests cost 0 credits. POST, PATCH, and DELETE cost 1 credit each. You start with 100 free credits. Check your balance: GET /credits
        


        
Next steps