Skip to main content
This guide walks you through starting every OTAS service locally, creating a project and agent from the dashboard, and sending your first event to Brain. By the end you’ll have a working session token and a logged API call visible in the analytics dashboard.

​
Prerequisites

You need one of the following setups:
  • Docker & Docker Compose (recommended) — no other dependencies required
  • Or: Python 3.10+, Node.js 18+, PostgreSQL 16, and Redis 7 installed locally

​
Steps

1

Start UASAM

UASAM manages users, projects, agents, and API keys. Start it with Docker Compose:
cd backend/uasam/docker-compose
docker-compose -f docker-compose-local.yml up
UASAM listens on http://localhost:8000. Wait until you see the Django server ready message before proceeding.
2

Start Brain

Brain receives and stores event logs. Start it in a second terminal:
cd backend/brain/docker-compose
docker-compose -f docker-compose-local.yml up
Brain listens on http://localhost:8002.
3

Start the frontend

The React dashboard connects to UASAM and Brain using the hardcoded endpoints in src/constants.ts (UASAM_ENDPOINT = http://localhost:8000, BRAIN_ENDPOINT = http://localhost:8002). Start it in a third terminal:
cd frontend/otas-frontend
npm install
npm run dev
The dashboard is available at http://localhost:5173.
If your backend services run on different hosts or ports, update UASAM_ENDPOINT and BRAIN_ENDPOINT in frontend/otas-frontend/src/constants.ts before starting the frontend.
4

Sign up

Open http://localhost:5173 and create an account. Provide your first name, last name, email, and a password of at least six characters. On success you receive a user JWT that is stored in the frontend and sent as X-OTAS-USER-TOKEN on every subsequent management request.
5

Create a project

From the dashboard, create a new project. Give it a name and an optional description and domain. OTAS creates a UserProjectMapping that assigns you the Admin privilege (privilege 1) for this project. Copy the project UUID — you’ll need it as X-OTAS-PROJECT-ID when calling management endpoints directly.
6

Create an agent and copy your AgentKey

Navigate to the Agents section of your project and create an agent. Provide a name, description, and provider (for example, Anthropic). OTAS creates the agent and immediately generates an AgentKey valid for 30 days.
Copy the full agent key now. It is only shown once. The key is stored hashed in the database and cannot be retrieved later.
The key has the format agent_<prefix>_<secret>. Use it as the value of the X-OTAS-AGENT-KEY header.
7

Create a session

At the start of every new agent run, create a session. The session token authenticates all event logs sent to Brain.
curl -X POST http://localhost:8000/api/agent/v1/session/create/ \
  -H "X-OTAS-AGENT-KEY: agent_<your_prefix>_<your_secret>" \
  -H "Content-Type: application/json" \
  -d '{"meta": {}}'
A successful response looks like:
{
  "status": 1,
  "status_description": "agent_session_created",
  "response": {
    "Header_value": "X-OTAS-AGENT-SESSION-TOKEN",
    "jwt_token": "<YOUR_SESSION_JWT>"
  }
}
Store the jwt_token value. Pass it as X-OTAS-AGENT-SESSION-TOKEN on every log request for this session.
You can pass arbitrary context in meta (task name, trace ID, inputs) to make sessions easier to identify in the dashboard.
8

Log your first event to Brain

After making an external API call, log it to Brain so it appears in your analytics:
curl -X POST http://localhost:8002/api/v1/backend/log/agent/ \
  -H "X-OTAS-AGENT-KEY: agent_<your_prefix>_<your_secret>" \
  -H "X-OTAS-AGENT-SESSION-TOKEN: <YOUR_SESSION_JWT>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<YOUR_PROJECT_UUID>",
    "path": "/api/v1/some-external-resource",
    "method": "POST",
    "status_code": 200,
    "latency_ms": 123.45,
    "request_size_bytes": 512,
    "response_size_bytes": 1024,
    "request_headers": "{\"Content-Type\": \"application/json\"}",
    "request_body": "{\"prompt\": \"hello\"}",
    "query_params": "",
    "post_data": "",
    "response_headers": "{\"Content-Type\": \"application/json\"}",
    "response_body": "{\"text\": \"world\"}",
    "request_content_type": "application/json",
    "response_content_type": "application/json",
    "custom_properties": {},
    "error": "",
    "metadata": {}
  }'
Return to the dashboard and open your agent’s session view. The event should appear with its path, status code, and latency.

​
What’s next

Now that you have a working integration, explore the full agent protocol and analytics capabilities:

Architecture overview

Understand how UASAM, Brain, and the frontend are connected.

Agent integration guide

Read the full Agent Manifest for in-domain and out-of-domain logging rules.

Build docs developers (and LLMs) love

Get started for freeTalk to us