Tela README

The wiki that writes itself — from the code you already ship.

   

Home · Pricing · Compare · MCP for agents · Docs

tela is a self-hostable, markdown-native team wiki built for a world where agents are first-class authors and readers. It pairs a Go + PostgreSQL backend with a React 19 / Milkdown editor, live Yjs collaboration, ranked full-text and semantic search, and a built-in Model Context Protocol (MCP) server — so the same knowledge base your team edits in the browser is one your agents can search, read, and write directly. Atlas, its documentation engine, turns the artifacts you already produce into maintained wiki pages. Your content stays canonical markdown forever — pages.body is markdown, there is no proprietary block store.

👉 Start at telawiki.com — the marketing site walks through what tela does (with pricing, a comparison, and the agent/MCP story), and the hosted instance has a free tier: no install, no card.

Why tela

• Atlas auto-doc-gen — point Atlas at your sources and it drafts and maintains real wiki pages, so docs track what you ship instead of rotting.
• Built-in MCP server — /api/mcp is part of the backend, not a bolt-on. Claude, Cursor, and other agents search, read, and author pages with scoped, per-tool write permissions.
• Semantic + full-text search — ranked PostgreSQL FTS works out of the box; add an embedder for pgvector-backed semantic retrieval and grounded "ask your docs" answers.
• Live collaboration — real-time multi-cursor editing over Yjs in a Milkdown editor, with comments, backlinks, and revision history.
• Teams that run themselves — users create orgs and invite teammates by email, no admin ticket. Flip a space to public and it becomes a login-free blog surface with per-author home pages.
• Self-host & own your markdown — pages.body is canonical markdown forever (no block table). Sync over WebDAV, export to zip/PDF, and run the whole stack with one make up.

Quickstart

You need Docker (with Compose) and make. The bundled stack builds every image via Compose, so no host Node or Go toolchain is required.

git clone https://github.com/zcag/tela.git
cd tela

# 1. Write deploy/.env from the example with strong generated secrets
#    (fills TELA_API_KEY_SECRET, TELA_SHARE_SECRET, TELA_PG_PASSWORD via openssl rand)
make setup

# 2. Edit deploy/.env — set TELA_PUBLIC_BASE_URL, and optionally
#    TELA_ADMIN_* and TELA_SMTP_* (see Configuration below)

# 3. Build and start the full stack
make up

The stack comes up behind Caddy on http://localhost:8780. On first boot tela runs its embedded migrations automatically and lands you on the /setup wizard to create the first admin — unless you set TELA_ADMIN_PASSWORD in deploy/.env, which bootstraps the admin non-interactively.

One-click cloud deploy

Prefer managed hosting over running Compose? Deploy the published multi-arch images straight to a platform:

After the first deploy, enable pgvector on the managed database once — CREATE EXTENSION IF NOT EXISTS vector; — then point the backend's TELA_PUBLIC_BASE_URL at your app's public URL. Or skip ops entirely with the free cloud tier.

Common targets:

make up         # build + start the stack on :8780 (auto-stamps git version/commit)
make down       # stop the stack
make logs       # tail logs from all services
make backup     # dump Postgres to ./backups/tela-<timestamp>.sql
make restore FILE=backups/tela-....sql
make clean FORCE=1   # stop and DELETE all volumes (destroys data)

make up is the same thing as running Compose directly — under the hood it's docker compose -f deploy/docker-compose.yml up -d --build (plus a forced proxy recreate so a changed Caddyfile re-mounts). The three load-bearing secrets must be set and stable across deploys: rotating TELA_SHARE_SECRET invalidates outstanding share cookies, and rotating TELA_API_KEY_SECRET invalidates every existing personal access token (PAT).

For full setup, TLS, backups, and upgrades see docs/self-hosting.md and the operations runbook docs/operations.md.

Local development

make dev        # backend (:8080) + frontend (:5173, proxies /api → :8080); boots a local dev Postgres
make be-dev     # backend only (go run; boots the dev Postgres on :55433)
make fe-dev     # frontend only (vite)
make test       # backend tests against a throwaway Postgres
make storybook  # component dev surface

If :8080 is taken on your box, run make dev DEV_BE_PORT=18080 so the backend and the vite /api proxy stay consistent.

Optional: semantic search out of the box

The bundled Compose stack ships an optional Ollama embedder behind a profile. Full-text search always works; this only lights up the semantic half:

docker compose -f deploy/docker-compose.yml --profile embed up -d
docker compose -f deploy/docker-compose.yml exec ollama ollama pull qwen3-embedding:0.6b
# then set TELA_RAG_EMBED_URL=http://ollama:11434 in deploy/.env and restart

Configuration

All configuration is environment-driven via deploy/.env (copy from deploy/.env.example). In the bundled Compose stack TELA_DATABASE_URL is auto-constructed from the TELA_PG_* vars — you only set it explicitly when running the backend against an external Postgres.

Required

Postgres

Bootstrap admin (optional)

Email (transactional + notifications)

With TELA_SMTP_HOST unset, tela logs confirmation/reset/notification links to stdout instead of sending (fine for dev / first boot). Works with any SMTP relay.

Custom domains & TLS (optional)

AI: semantic retrieval, ask-your-docs, Atlas (all optional, ship dark)

These features ship dark — unset means the relevant endpoints return 503 and nothing is computed. Point them at your own Ollama / OpenAI-compatible endpoints, the bundled --profile embed Ollama, or tela cloud's managed endpoints (authenticated with a telawiki.com PAT).

Auth: MCP OAuth & federated sign-in (optional)

Billing (optional, ships dark)

Services, sync & ops (optional)

The split/deploy topology adds image-ref and Umami-analytics vars (TELA_BACKEND_IMAGE, TELA_FRONTEND_IMAGE, UMAMI_APP_SECRET, UMAMI_DB_PASSWORD, …). See deploy/.env.example and docs/deploy.md.

Connect your agents (MCP)

tela's MCP server is built into the backend at /api/mcp — it self-authenticates with a personal access token (PAT) as a bearer header. Modern hosts speak HTTP transport directly:

https://telawiki.com/api/mcp            # tela cloud
https://your-host.example.com/api/mcp   # your self-hosted origin

For hosts that can't speak HTTP transport (or want a stdio bridge), the tela-mcp npm package is a thin stdio↔HTTP proxy to the same endpoint — no second tool implementation to drift. Add it to your MCP client config (e.g. Claude Desktop / Cursor):

{
  "mcpServers": {
    "tela": {
      "command": "npx",
      "args": ["-y", "tela-mcp"],
      "env": {
        "TELA_BASE_URL": "https://telawiki.com",
        "TELA_API_KEY": "tela_pat_xxxxxxxx"
      }
    }
  }
}

Point TELA_BASE_URL at your own origin to use a self-hosted instance. Generate a PAT in Settings → API tokens; per-tool write permission is enforced server-side. The proxy requires Node ≥ 20. See mcp/README.md for the full tool catalog and troubleshooting.

One-click install

Both buttons add the HTTP endpoint; auth is handled by OAuth on first use, so no token goes in the link.

Per-client setup

HTTP-transport hosts connect to the endpoint directly and sign in via OAuth. stdio-only hosts use the tela-mcp proxy with a PAT (TELA_BASE_URL + TELA_API_KEY).

Claude Code (CLI, HTTP):

claude mcp add --transport http tela https://telawiki.com/api/mcp

Cursor (HTTP) — use the button above, or add to ~/.cursor/mcp.json:

{ "mcpServers": { "tela": { "url": "https://telawiki.com/api/mcp" } } }

VS Code (HTTP) — use the button above, or:

code --add-mcp '{"name":"tela","type":"http","url":"https://telawiki.com/api/mcp"}'

ChatGPT — install Tela from the plugin directory and sign in. Nothing to paste, no Developer Mode. (The directory plugin talks to the hosted service; for a self-hosted instance add a custom connector with your own URL, as below.)

Claude.ai / self-hosted ChatGPT (OAuth connector) — add a custom connector and paste the URL; complete the sign-in:

https://telawiki.com/api/mcp

Claude Desktop (stdio proxy) — claude_desktop_config.json:

{
  "mcpServers": {
    "tela": {
      "command": "npx",
      "args": ["-y", "tela-mcp"],
      "env": { "TELA_BASE_URL": "https://telawiki.com", "TELA_API_KEY": "tela_pat_xxxxxxxx" }
    }
  }
}

Windsurf (stdio proxy) — ~/.codeium/windsurf/mcp_config.json, same mcpServers shape as Claude Desktop above.

Codex (stdio proxy) — ~/.codex/config.toml:

[mcp_servers.tela]
command = "npx"
args = ["-y", "tela-mcp"]
env = { TELA_BASE_URL = "https://telawiki.com", TELA_API_KEY = "tela_pat_xxxxxxxx" }

A machine-discovery manifest is published at /.well-known/mcp.json.

Screenshots

Ranked full-text search across every space you can read, with the matching line in context:

Atlas documents a repo and then audits its own coverage — 6/6 must-cover surfaces documented, 42 citations, and the exact file:line gaps it hasn't covered:

Architecture

• Backend — Go (module github.com/zcag/tela/backend, entry cmd/tela). Hand-written database/sql over the pgx/v5 stdlib driver — no ORM, no sqlc. Embedded, forward-only SQL migrations run automatically on boot.
• Database — PostgreSQL 17 with the pgvector extension (pgvector/pgvector:pg17). FTS lives in pages.search_tsv (ranked ts_rank_cd); semantic chunks live in page_chunks.embedding vector(1024).
• Frontend — React 19 + Vite + TypeScript + Tailwind v4 + Radix + a Milkdown (@milkdown/kit) editor, with TanStack Query/Router, Orama, cmdk, and Storybook. Owned, token-driven UI components only.
• Live collaboration — Yjs + y-prosemirror over a custom WebSocket transport, scoped tightly to src/lib/collab/* and the collab branch of the editor; it rebases onto the canonical markdown on save.
• Built-in MCP — the tool/resource surface lives in the Go backend (internal/api/mcp*.go) and calls the same core functions the REST routes do, so there is one implementation. mcp/ is a dumb stdio↔HTTP pipe published as tela-mcp on npm.
• Atlas — the documentation engine that drafts and maintains wiki pages from your sources, sharing the configured LLM endpoint.
• Render sidecars — Gotenberg for HTML→PDF export; a Slidev deck sidecar for presentation pages.
• Edge — Caddy serves the SPA, the API, the marketing landing at the apex, and (in direct-TLS mode) on-demand certificates for org custom domains.

Deeper internals, ops, and gotchas live in docs/ — start with docs/architecture.md, and docs/decisions.md for the rationale (PostgreSQL, custom collab transport, MCP-as-thin-client).

Self-host vs cloud

• Self-host — run the whole stack with make up (or docker compose). You own the data, the markdown, and the Postgres volume; AI features are bring-your-own-endpoint (or the bundled Ollama profile). The split/registry deploy topology for shared-edge boxes is in docs/deploy.md.
• Cloud — a managed instance is hosted at telawiki.com with a free tier, plus optional managed semantic search and ask-your-docs so you don't have to run an embedder or LLM yourself.

Both run the same code from this repository.

Contributing

• Commit format: type(scope): summary (e.g. feat(backend): hybrid chunk search). Concise messages, no co-author trailer.
• No issue/task tracker — please don't open GitHub issues or reference #NNN. Discuss via pull requests.
• Backend changes use hand-written SQL and a new forward-only NNNN_name.sql migration (never edit an applied one). Frontend changes use owned Radix/token-based primitives — no hardcoded hex/px, no third-party component kits.
• Run make test (backend) and npm run build in frontend/ before sending a change. See CLAUDE.md and docs/ for the full conventions.

Security

Please report security issues privately to tela@telawiki.com. Do not open a public issue or PR for a vulnerability. Note that a missing or rotated TELA_API_KEY_SECRET / TELA_SHARE_SECRET leads to forgeable tokens — keep them set and stable.

License

tela is open core. Copyright © tela contributors. The Community core — the whole product — is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0): self-host, modify, and redistribute under its terms (run a modified version as a network service and you must offer your users the corresponding source). The tela-mcp npm package is published under AGPL-3.0-only. For a commercial license without AGPL obligations (e.g. to embed or offer tela as a closed service), contact the maintainer.

The Enterprise Edition (backend/internal/ee/, source-available, not AGPL) adds the company-of-record layer (SSO, audit, SCIM, governance) and requires a license key for production use — see backend/internal/ee/LICENSE.md. Full structure in docs/licensing.md.

"tela", the tela name, and the tela logo are trademarks and are not licensed under the AGPL — see TRADEMARK.md. You may run and fork the code, but you may not use the tela branding for a redistributed or hosted version without permission.