Teros

The open-source AI agent operating system.

Build, run, and extend AI agents that actually get things done.

Website · Documentation · Contributing · Discord

curl -fsSL https://get.teros.ai | bash

Requires Docker. Takes ~2 minutes.

Nua reads Sentry errors and creates Linear issues automatically

Teros is an open-source platform for building and running AI agents with real tool capabilities. Think of it as an operating system for AI — agents live inside it, have access to tools (MCAs), connect to your services, and work for you across tasks.

Unlike chat wrappers, Teros agents are persistent, multi-tool, and autonomous. They can browse the web, write and run code, manage your calendar, send emails, interact with GitHub, deploy to Railway, and much more — all through a clean, extensible architecture.

You talk to an agent → The agent uses tools → Things actually happen

AI personas with a personality, memory, and access to tools. Each agent has its own system prompt, preferred LLM provider, and set of installed apps. You can have multiple agents for different purposes — a coding assistant, a project manager, a research agent.

The tool system. An MCA is a self-contained package that gives agents new capabilities — file system access, email, calendar, databases, APIs. Teros ships with 43 MCAs out of the box and makes it easy to build your own.

Shared environments where agents and apps are organized together. A workspace can have multiple agents collaborating on the same project, with shared context and board-based task management.

LLM backends. Teros supports Anthropic, OpenAI, OpenRouter, Ollama (local), Zhipu, and OAuth-based providers like Claude Max and ChatGPT Pro/Plus (Codex). Each agent can use a different model.

┌──────────────────────────────────────────────────────────────────┐
│                           Teros                                  │
│                                                                  │
│   ┌──────────────┐   WebSocket   ┌──────────────────┐            │
│   │   Frontend   │ ◄──────────── │    Backend       │            │
│   │  React Native│ ──────────── ►│    Node.js       │            │
│   │  (Expo Web)  │               │    WsRouter      │            │
│   └──────────────┘               └───────┬──────────┘            │
│                                          │                       │
│                             ┌────────────┼─────────────┐         │
│                             │            │             │         │
│                        ┌────▼────┐  ┌────▼────┐  ┌─────▼─────┐   │
│                        │ MongoDB │  │  MCAs   │  │   LLM     │   │
│                        │         │  │ (tools) │  │ Providers │   │
│                        └─────────┘  └─────────┘  └───────────┘   │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘

teros/
├── packages/
│   ├── app/          # React Native / Expo frontend
│   ├── backend/      # Node.js WebSocket server
│   ├── core/         # LLM adapters, conversation engine
│   ├── shared/       # Protocol types, Zod schemas
│   └── mca-sdk/      # SDK for building MCAs
│
├── mcas/             # 43 ready-to-use tool packages
│   ├── mca.teros.bash
│   ├── mca.teros.filesystem
│   ├── mca.teros.memory
│   ├── mca.google.gmail
│   ├── mca.google.calendar
│   ├── mca.github
│   ├── mca.notion
│   ├── mca.linear
│   └── ... (43 total)
│
├── docs/             # Architecture, RFCs, runbooks
└── scripts/          # Build and sync utilities

Teros ships with 43 MCAs across several categories:

Productivity gmail · google-calendar · google-drive · google-contacts · microsoft-outlook · notion · todoist · trello · monday · linear

Development github · railway · sentry · docker-env · bash · filesystem · playwright

AI & Media replicate · higgsfield · elevenlabs · perplexity · file-processor

Platform memory · scheduler · conversations · board-manager · board-runner · messaging · webfetch · datetime

Integrations canva · figma · intercom · homey · minio · kelify

• Docker and Docker Compose

git clone https://github.com/teros-hq/teros.git
cd teros
cp .env.example .env
bash scripts/setup-secrets.sh
docker compose up

Open http://localhost:10002.

# Install dependencies
yarn install

# Build all packages
yarn build

# Start MongoDB
docker compose up -d mongodb

# Terminal 1 — backend (with hot reload)
yarn dev:backend

# Terminal 2 — frontend
yarn dev:app

An MCA is a directory with a manifest.json, a tools.json (auto-generated), and a src/ folder. Each tool lives in its own file. The MCA SDK handles the HTTP transport and connection to the backend automatically.

mcas/mca.my-tool/
├── manifest.json        # Metadata, secrets, availability, runtime config
├── tools.json           # Tool schemas (auto-generated by sync script)
├── package.json
├── tsconfig.json
└── src/
    ├── index.ts         # McaServer setup, tool registration, server.start()
    ├── lib/             # API client, auth helpers, shared utilities
    └── tools/
        ├── index.ts     # Re-exports all tools
        ├── my-tool.ts   # One file per tool
        └── other-tool.ts

// src/tools/my-tool.ts
import type { HttpToolConfig as ToolConfig } from '@teros/mca-sdk';

export const myTool: ToolConfig = {
  description: 'Does something useful',
  parameters: {
    type: 'object',
    properties: {
      query: { type: 'string', description: 'The query to process' },
    },
    required: ['query'],
  },
  handler: async (args, context) => {
    const { query } = args as { query: string };
    // context.getUserSecrets() — fetch API keys configured by the user
    return { result: `You asked: ${query}` };
  },
};

// src/index.ts
import { McaServer } from '@teros/mca-sdk';
import { myTool } from './tools';

const server = new McaServer({ id: 'mca.my-tool', name: 'My Tool', version: '1.0.0' });

server.tool('my-tool', myTool);

server.start();

See CONTRIBUTING.md for the full MCA development guide.

Teros is open source and contributions are welcome.

# Fork, clone, create a branch
git checkout -b feat/my-feature

# Make changes, test locally
yarn dev:backend

# Submit a PR

See CONTRIBUTING.md for guidelines, code style, and how to build and submit new MCAs.

FSL-1.1-Apache-2.0 — free for personal and non-commercial use. Converts to Apache 2.0 on the second anniversary of each release.