Agentic Organization

Self-hosted platform for companies to manage AI agents as first-class members of their org chart.

Define agents per personnel, assign skills and policies, run autonomous flows, and onboard your entire organization in a single AI-assisted conversation.

---

Features

Feature	Status
Multi-company management	✅
Department + personnel CRUD	✅
Agent configuration (model, skills, status)	✅
AI Onboarding — web search + AI chat → full org structure in minutes	✅
Company Skills Library — Markdown-based skill definitions assignable to multiple agents	✅
Policies Management — company / department / agent-scoped policies with Markdown editor	✅
Org chart visualization (interactive tree view)	✅
AI provider key management (Anthropic, OpenAI, Google Gemini, Mistral, Qwen, Ollama, LM Studio)	✅
Autonomous Flows — cron-scheduled agent tasks delivered to inbox	✅
Task Requests — route tasks to best-matched agent by dept + skill	✅
Agent-to-Agent (A2A) delegation with human approval + auto-compilation	✅
Orchestrator agents — Council Agent pattern with parallel specialist delegation	✅
Token telemetry — per-message token tracking across all providers	✅
Long-term agent memory — session summaries stored and injected into future context	✅
Image generation in flows — Qwen Image / DALL-E via DashScope task API	✅
Real-time AI chat sessions (SSE streaming)	✅
First-time setup wizard (no hardcoded credentials)	✅
JWT auth + bcrypt passwords + Fernet-encrypted provider keys	✅
Audit log	✅
Multi-language support (TR / EN)	✅
Company-level authorization (multi-company users)	✅
Structured JSON logging (logs/app.log)	✅
Database migrations (Alembic)	✅
Login rate limiting (Nginx)	✅
On-demand backup to S3/R2/MinIO (Settings → Backup)	✅
Social media agent skills (Instagram Business + WhatsApp Cloud API)	✅
Telegram notification integration	✅
GitHub / GitLab / Gitea sync (config + policy Markdown files)	✅
Live dashboard — company + personal telemetry (tokens, sessions, memories, A2A SLA)	✅
Change request workflow — dept-head + admin two-step approval with Git commit	✅
ERP / custom database query skills — agents query live databases via SQL	✅
PostgreSQL + pgvector (RAG over agent memories, sessions and task history); SQLite for local dev	✅
Multi-tenant subdomains (<company>.agent.fab.engineering) — see CLOUD_DEPLOY.md	✅
Multi-worker safe startup (single scheduler leader, serialized DB init)	✅
Agentic OS layer — gateway, policy engine, tamper-evident audit, 3pa CLI + sandbox (see below)	✅

---

Agentic OS Layer (Developer Workstations)

The web UI stays the main surface for non-developer staff. Developers can additionally run opencode on their own machine, inside a sandbox, with every model call and tool call going through this server:

Component	Where	What it does
LLM Gateway	backend/api/gateway.py	OpenAI-compatible /v1/chat/completions + /v1/models; per-persona token → company provider key; model allowlist, quota, rate limit, usage telemetry
Policy Engine	backend/services/policy_engine.py	Fail-closed allow / ask / deny for skills and tool calls, bash AST matching, parent-department inheritance
Tamper-evident audit	backend/services/audit_chain.py, audit_anchor.py	Per-tenant hash chain, external anchoring (local log / S3 Object Lock), 3pa audit verify
LLM severity scoring	backend/services/audit_severity.py	Scores audit events, Telegram alerts, per-company opt-in, policy auto-escalation
Persona tokens	backend/services/gateway_auth.py, api/workstation.py	Short-lived access + refresh tokens, rotation, revocation, heartbeat, optional OIDC exchange
Signed config	backend/api/well_known.py	Ed25519-signed /.well-known/opencode, plus API catalog, A2A agent card and /auth.md
MCP server	backend/api/mcp_server.py	Exposes skills / A2A / inbox / policies to opencode over MCP
Signed command channel	api/workstation.py	Server → workstation commands, signed and acknowledged
3pa CLI	packages/cli	init, login, run, doctor, policy, audit, refresh, logout, status, start, stop
Org plugin	packages/agent-plugin	opencode plugin: policy check before each tool, audit reporting, taint tracking

Design and rationale: docs/ROADMAP.md, docs/architecture/agentic-os.md, docs/adr/ (ADR-0001 … ADR-0021).

---

Department Workspace (fab)

Non-developer departments work from a terminal client, fab, attached to a per-person server-side workspace with one agent per person (ADR-0014, 0018–0021). It reuses the same gateway, policy engine and audit chain.

Component	Where
fab client (login, sidebar, agent pane, fab workspace, fab sync, "My review")	packages/tui
Workspace lifecycle API (behind a WorkspaceRuntime interface)	backend/api/workspaces.py
Prompt assembly with token budget, Jev intent classifier	backend/services/context_assembly.py, intent.py
Work review, fit rating, rubric, calibration, training-need signal	backend/api/work_review.py, backend/services/
Workspace image (LibreOffice, PDF tools, headless Chromium)	sandbox/workspace/

Not production-ready: there is no real workspace runtime yet (only a test FakeRuntime), and fit rating has not been measured against the live TypeSafe Jev API or reviewed legally, so work review, rating, manager sharing and intent classification all ship off per company. Details, switches and verification steps: https://agent-docs.fab.engineering/docs/fab/overview.

---

Documentation

The docs source lives in this repository under apps/docs, so a change to code, an ADR and its documentation can land in one pull request.

Product and platform guides (onboarding, A2A delegation, autonomous flows, change requests, personnel portal, …) live on the docs site, not in this README: https://agent-docs.fab.engineering (source: apps/docs; the old fab-agent/docs repository is retired). Architecture decisions stay here in docs/adr/.

---

Quick Start

Requirements

• Docker + Docker Compose or Python 3.11+ and Node.js 20+
• At least one active AI provider API key (Anthropic, OpenAI, Google, Mistral, Qwen, or a local model via Ollama / LM Studio)

---

Option A — Docker (Recommended)

git clone https://github.com/fab-agent/agentic-organization.git
cd agentic-organization

cp backend/.env.example backend/.env
# Edit .env — JWT_SECRET is required (openssl rand -hex 32), AI provider keys are optional

docker compose up --build

This starts PostgreSQL 16 + pgvector (db), the backend and the frontend.

UI → http://localhost:5173
API → http://localhost:8000

Production (Nginx + PostgreSQL, 2 uvicorn workers):

bash install.sh     # checks Docker, runs setup-env.sh (root .env), renders nginx.conf, starts the stack
# or, with .env and nginx.conf already in place:
docker compose -f docker-compose.prod.yml up -d --build

UI + API → http://localhost (Nginx on port 80/443, API under /api)
Login endpoint is rate-limited to 5 attempts/minute per IP. The root .env must set POSTGRES_PASSWORD and a strong JWT_SECRET — with ENVIRONMENT=production the backend refuses to start on a placeholder or short secret.

For the multi-tenant subdomain setup see CLOUD_DEPLOY.md (docker-compose.cloud.yml).

---

Option B — Manual (Development)

Backend:

cd backend
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt -r requirements-dev.txt
uvicorn main:app --port 8000

Without DATABASE_URL the backend uses SQLite (data/app.db) — fine for development. Production, pgvector search and the Postgres smoke tests use DATABASE_URL=postgresql+psycopg2://…; the db service from docker-compose.yml exposes one on 127.0.0.1:5432.

Dependencies are locked: edit backend/requirements.in (runtime) or backend/requirements-dev.in (test/lint), then regenerate the pinned requirements*.txt with the uv pip compile commands at the top of requirements.in. Never edit the .txt lockfiles by hand.

Frontend (separate terminal):

cd frontend
npm install
cp .env.example .env          # VITE_API_URL=http://localhost:8000
npm run dev                   # http://localhost:5173

---

Option C — HTTPS with Cloudflare Tunnel (Recommended for Production)

No port forwarding or SSL certificates needed. Cloudflare Tunnel handles everything.

# 1. Install cloudflared
curl -L https://pkg.cloudflare.com/cloudflare-main.gpg | sudo gpg --dearmor -o /usr/share/keyrings/cloudflare-main.gpg
echo 'deb [signed-by=/usr/share/keyrings/cloudflare-main.gpg] https://pkg.cloudflare.com/cloudflared jammy main' | sudo tee /etc/apt/sources.list.d/cloudflared.list
sudo apt update && sudo apt install cloudflared

# 2. Login and create tunnel
cloudflared tunnel login
cloudflared tunnel create my-org-platform

# 3. Create config at ~/.cloudflared/config.yml
cat > ~/.cloudflared/config.yml << EOF
tunnel: <TUNNEL_ID>
credentials-file: /root/.cloudflared/<TUNNEL_ID>.json

ingress:
  - hostname: app.your-domain.com
    service: http://localhost:80
  - service: http_status:404
EOF

# 4. Route DNS
cloudflared tunnel route dns my-org-platform app.your-domain.com

# 5. Start
cloudflared tunnel run my-org-platform

The production stack builds the frontend with VITE_API_URL=/api, so the UI and API share the tunnel hostname — no rebuild needed. Set APP_URL=https://app.your-domain.com in .env so invite links and CORS use the public origin.

---

First Launch

On first open, a setup wizard asks for:

• Full name
• Company name
• E-mail
• Password

This creates the founder account. No hardcoded credentials — every install gets its own admin.

---

Usage

After the first launch, follow the guides on the docs site: https://agent-docs.fab.engineering (AI onboarding at Settings → AI ile Kur is the recommended first step).

---

Architecture

Path	What
backend/	FastAPI + SQLModel (PostgreSQL + pgvector; SQLite for dev): api/, services/, models.py, migrations/, tests/
frontend/	SvelteKit web UI (frozen for new product features, see ADR-0014)
packages/cli	3pa workstation CLI
packages/agent-plugin	opencode org plugin (policy, audit, taint tracking)
packages/tui	fab, the department terminal client (Rust + Ratatui)
apps/docs	Documentation site (Docusaurus, TR/EN) → agent-docs.fab.engineering
apps/landing	Marketing site (static + Worker) → agent.fab.engineering
sandbox/	Developer sandbox + egress proxy; sandbox/workspace/ is the department workspace image
docs/	ROADMAP.md, architecture/, adr/
.github/workflows/	One path-scoped workflow per component, plus adr-guard

Data Model

Company ──< Department ──< Personnel ──── AgentConfig ──< AgentSkillLink ──> CompanySkill
   │                            │              │
   │                            │         AgentSession ──< SessionMessage (tokens_used)
   │                            │              │
   │                            │         AgentMemory (long-term session summaries)
   │                            │         EmbeddingRecord (RAG vectors)
   │                            │
   │                     Flow (cron schedule → InboxMessage)
   │                     TaskRequest (dept+skill routing → agent run)
   │                     A2ARequest (from_agent → to_agent → human approver → compiled report)
   │                     WorkJournalEntry
   │
   ├── Policy (scope: company | department | agent) + Department/AgentPolicyLink, PolicyConfig
   ├── ChangeRequest (dept-head → admin → Git commit)
   ├── DatabaseConnection (encrypted DSN for SQL query skills)
   ├── ProviderKey, GitConfig, TelegramConfig
   └── User ──< CompanyMember

Agentic OS: AuditEvent (hash chain) · AuditSeverity · GatewayUsage · PersonaTokenState ·
            RevokedToken · PersonaHeartbeat · PersonaCommand

---

API Reference

• Swagger UI → http://localhost:8000/docs
• ReDoc → http://localhost:8000/redoc

Web UI endpoints use Authorization: Bearer <user JWT>; public ones are /auth/token, /auth/setup-status, /auth/setup, /auth/demo/*, /tenant/resolve, /system/version and /.well-known/*. Workstation endpoints (/v1/*, /workstation/*, /audit/ingest, /mcp) use short-lived persona tokens issued by 3pa login.

---

Environment Variables

Set in backend/.env (dev) or the root .env (production, generated by setup-env.sh).

# Required — at least 32 chars; with ENVIRONMENT=production the app refuses
# to start on a placeholder or short value. Generate: openssl rand -hex 32
JWT_SECRET=

# Database — default sqlite:///./data/app.db; the compose files set PostgreSQL
DATABASE_URL=postgresql+psycopg2://agentic:<password>@db:5432/agentic
POSTGRES_PASSWORD=             # used by the compose files

# Runtime (optional)
ENVIRONMENT=development        # production in the prod/cloud compose files
APP_URL=http://localhost:5173  # invite links + default CORS origin
CORS_ORIGINS=                  # comma-separated; default APP_URL (+ localhost:5173 outside production)
SCHEDULER_ENABLED=true         # one worker runs cron flows / jobs via data/scheduler.lock

# Email (optional) — without it, invite tokens are printed to the log
RESEND_API_KEY=
[email protected]

# AI provider keys (optional) — imported once on first start; can also be added in Settings
ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GOOGLE_API_KEY=
MISTRAL_API_KEY=
QWEN_API_KEY=

# Agentic OS (optional)
PUBLIC_BASE_URL=               # public API base used in /.well-known documents
PERSONA_TOKEN_TTL_MINUTES=60
PERSONA_REFRESH_TTL_HOURS=12

# Department workspace / work review (optional; every feature here is off per company by default)
TYPESAFE_API_KEY=              # Jev: intent classification, fit rating, calibration (never commit)
WORKSPACE_RUNTIME=             # `fake` = tests only; no real runtime exists yet
PROMPT_BUDGET_TOKENS=2000
INTENT_TIMEOUT_SECONDS=1.5
INTENT_MIN_PROMPT_TOKENS=1500
WORK_REVIEW_MIN_GROUP=3        # smallest group shown in aggregates

Telegram, Git, social media, backup and database connections are configured per company from Settings, not through environment variables.

---

Testing

cd backend
pip install -r requirements.txt -r requirements-dev.txt
pytest tests/ -v                     # SQLite; Postgres smoke tests are skipped
ruff check . && ruff format --check .

cd ../frontend && npm run check      # svelte-check

CI (.github/workflows/) runs lint, svelte-check and pytest on every PR, plus a real PostgreSQL + pgvector job and separate suites for the gateway, policy engine, CLI, plugin and sandbox.

---

Roadmap

Status and next steps: docs/ROADMAP.md. Open product ideas: WhatsApp task alerts, visual flow builder, agent marketplace, timezone-aware datetimes in models.py (then lift the sqlmodel<0.0.25 cap).

---

License

Commons Clause + MIT — Free to use, fork, and self-host for your own organization. Selling, white-labeling, or offering this software as a hosted or managed service to third parties requires a commercial license.

Contact [email protected] for commercial licensing.

---

Built by Fabrika Yazılım · Istanbul · [email protected]