From deff7c6b245c39791065670cd550cc43c8d674a7 Mon Sep 17 00:00:00 2001 From: Maneek21 <208369276+Maneek21@users.noreply.github.com> Date: Fri, 11 Sep 2026 22:19:01 +0530 Subject: [PATCH] docs: refresh walkthrough and self-hosting quick start --- .env.example | 5 +- CONTRIBUTING.md | 2 + FEATURES.md | 8 +- README.md | 136 ++++++++++++-------------- docs/current-limitations.md | 9 +- docs/self-hosting-vps-domain-https.md | 2 +- docs/self-hosting.md | 133 ++++++++++++++++++++++--- 7 files changed, 196 insertions(+), 99 deletions(-) diff --git a/.env.example b/.env.example index 9fa702d3..246dc393 100644 --- a/.env.example +++ b/.env.example @@ -2,7 +2,7 @@ # Deft — Environment Configuration # Copy this to .env and fill in your values. # -# Required for first boot: POSTGRES_PASSWORD, JWT_SECRET, JWT_REFRESH_SECRET +# Required for Docker first boot: POSTGRES_PASSWORD, JWT_SECRET, JWT_REFRESH_SECRET, ENCRYPTION_KEY # AI features need at least one provider key (see section 3) or per-org BYOK. # Everything else is optional unless noted. # ═══════════════════════════════════════════════════════ @@ -27,7 +27,8 @@ JWT_SECRET=change-me-to-a-random-string JWT_REFRESH_SECRET=change-me-to-another-random-string # Symmetric key for encrypting per-org BYOK API keys at rest in orgs.ai_config. -# Production requires a unique, non-placeholder value of at least 32 characters. +# Docker runs in production mode, including local evaluation. REQUIRED: a unique, +# non-placeholder value of at least 32 characters. Generate: openssl rand -hex 32 ENCRYPTION_KEY=CHANGE_ME_WITH_AT_LEAST_32_RANDOM_CHARACTERS # ── 3. AI provider keys (optional fallbacks) ────────── diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fe59e580..626f90c6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,6 +25,8 @@ pnpm install cp .env.example .env createdb deft +# Set DATABASE_URL for this database and generate the four secrets in .env. +# See docs/self-hosting.md before continuing. pnpm db:push-full pnpm db:seed pnpm dev diff --git a/FEATURES.md b/FEATURES.md index 009f7ce4..c74db7e1 100644 --- a/FEATURES.md +++ b/FEATURES.md @@ -126,7 +126,9 @@ Human employees can connect their own AI client from Settings -> Connections. - Read-only and work-capable scope bundles - Tokens act as the user who created them and inherit that user's workspace access - Connection history, last use, recent actions, scopes, and revocation -- Idempotency support on write tools to reduce duplicate agent actions +- Tool-specific idempotency support to reduce duplicate writes; clients must follow the selected tool's retry contract + +Personal native writes act under the user's scopes and normal permissions; they do not automatically enter the Agent Employee approval queue. A `write:workspace` grant can include the user's permitted approval actions. See [identity and approval boundaries](docs/self-hosting.md#identity-approvals-and-action-history). Representative MCP tools cover: @@ -161,7 +163,7 @@ Deft supports provider-neutral AI configuration: - OpenAI-compatible endpoints - Local Ollama-style endpoints -Provider keys are optional. Core workspace functionality remains available without AI. +Provider keys are optional. Core workspace functionality remains available without AI. Configured models can receive prompts and workspace context; embedding/transcription providers can receive text/audio. Personal MCP clients use their own provider settings. See [AI data flow](docs/self-hosting.md#ai-data-flow). ## Self-hosting and operations @@ -174,7 +176,7 @@ Provider keys are optional. Core workspace functionality remains available witho - Production guidance for VPS, domain, HTTPS, and reverse proxy setup - Synthetic 60-person certification tooling for isolation, bulk operations, job backlog, notification volume, and recovery exercises -Fresh installs use `pnpm db:push-full`. Supported release-to-release upgrades use `pnpm db:upgrade` from the `v0.2.0-preview.1` baseline; see [current limitations](docs/current-limitations.md). +Fresh installs use `init` (`pnpm db:push-full` plus platform seed). Supported versioned upgrades begin at `v0.2.0-preview.1` and use the backup-first `pnpm selfhost:upgrade` flow. Upgrades are forward-only; recovery requires the previous image, database, uploads, and configuration. See [self-hosting](docs/self-hosting.md#upgrading). ## Apps and Modules diff --git a/README.md b/README.md index f47c9ad3..3e29ed3d 100644 --- a/README.md +++ b/README.md @@ -8,21 +8,68 @@ [Website](https://deft.ing) | [Self-hosting guide](docs/self-hosting.md) | [Contributing](CONTRIBUTING.md) -**Try Deft:** [install a workspace, connect your AI client, or build an internal App](docs/getting-started.md). The latest downloadable image is `v0.3.0-preview.15`. See the [current availability map](docs/product-status.md) before enabling an experimental feature. +Deft is a self-hostable, open-source workspace where people and AI agents share chat, tasks, knowledge, calendar context, approvals, and action history. -![Where humans and agents work together.](docs/assets/repository/hero.png) +Capture a team discussion into knowledge, ask Defty to propose a task using that context, review and approve the proposal, and keep the agreed details in the resulting task. -Deft is a self-hostable, open-source workspace where people and AI agents share the same chat, tasks, knowledge, calendar context, approvals, and receipts. +**Alpha:** for technical evaluation and controlled pilots. The walkthrough uses **seeded demo data**; it is not evidence of a live customer workspace or an active external agent runtime. -Instead of pasting fragments from Slack, Notion, and a task tracker into an AI chat, connect Codex, Claude, ChatGPT, or your own agent to the work record your team already uses. +[![Watch the full walkthrough — 5:09](https://i.ytimg.com/vi/7z9EH4c9k2o/hqdefault.jpg)](https://youtu.be/7z9EH4c9k2o) + +[**Watch the full walkthrough — 5:09.**](https://youtu.be/7z9EH4c9k2o) + +## Quick start with Docker + +Use the prebuilt [v0.3.0-preview.15 release](https://github.com/Maneek21/Deft/releases/tag/v0.3.0-preview.15) for evaluation. It targets **Linux amd64** and needs Docker Desktop or Docker Engine with Compose v2. An AI provider is optional. No source build, Node.js, or pnpm is needed for this path. + +Download `docker-compose.yml`, `compose.prod.yml`, `compose.release.yml`, and `default.env.example` from that release into a **new directory**. In Bash (macOS, Linux, or Git Bash on Windows): + +```bash +cp default.env.example .env +openssl rand -hex 32 # POSTGRES_PASSWORD +openssl rand -hex 32 # JWT_SECRET +openssl rand -hex 32 # JWT_REFRESH_SECRET +openssl rand -hex 32 # ENCRYPTION_KEY +``` + +Paste each independently generated secret into its corresponding `.env` variable. All four are required for Docker, including local evaluation. Keep the encryption key with your backups. Leave AI keys empty and `OLLAMA_URL` commented unless you intend to configure a provider. + +Add this pinned release image to `.env`: + +```dotenv +DEFT_IMAGE=ghcr.io/maneek21/deft@sha256:665a66083adaaf9db876fa815203c854509c5fdde72b89a0db212fe2e07d398b +``` + +Then run, from that directory: + +```bash +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml config --quiet +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml pull +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml up -d postgres +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml run --rm init +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml up -d deft +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml run --rm doctor +docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml run --rm smoke +``` + +Open [http://localhost:3000](http://localhost:3000) and create the first account, which owns the workspace. Subsequent users join by invitation. This creates an empty workspace with the platform bundle, not the video's demo records. Create a chat message and a task to try the core workspace without AI. + +Use `init` only with a fresh database. For custom ports, public URLs, image verification, source builds, backups, and upgrades, follow the [self-hosting guide](docs/self-hosting.md). Versioned upgrades start at `v0.2.0-preview.1`; use the backup-first upgrade flow for existing workspaces. Historical releases through `v0.2.0-preview.4` retain their shipped BSL 1.1 license; the selected release is AGPL-3.0-only. + +**Try Deft:** [install a workspace, connect your AI client, or build an internal App](docs/getting-started.md). See the [current availability map](docs/product-status.md) before enabling an experimental feature. + +[Architecture](#architecture) · [Current limitations](docs/current-limitations.md) · [Licensing](#license) ## The core loop -1. **Work happens in context.** People discuss an issue in chat, update a task, write a note, or record a decision. -2. **An agent reads the same workspace.** Defty, an agent employee, or a personal MCP client can retrieve the relevant messages, tasks, wiki pages, people, and calendar context. -3. **Governed actions can require review.** Employee actions follow their approval policy, with proposed changes shown in conversation cards and the approval inbox. Personal MCP writes use the authorizing person's permissions and scopes. -4. **The result lands in Deft.** Tasks, messages, notes, wiki pages, and status changes become part of the shared record. -5. **Governed agent actions leave receipts.** Deft records the actor, outcome, and result for actions that pass through its governed execution paths. +1. **Capture the discussion.** Save useful decisions and references in Knowledge with links back to their source conversation. +2. **Ask Defty for a task.** With an AI provider configured, Defty can use workspace context to propose the title, owner, dates, and description. +3. **Review and approve.** Under a policy requiring review, inspect the proposed details before approving. Trust settings can permit some actions to execute automatically. +4. **Keep the agreed details.** The task stores the approved content, and governed agent actions have approval history and receipts to inspect. + +Optional video chapters: [Knowledge capture — 1:09](https://youtu.be/7z9EH4c9k2o?t=69) · [Defty task request and approval — 2:06](https://youtu.be/7z9EH4c9k2o?t=126) · [ChatGPT connection and workspace read/write — 3:25](https://youtu.be/7z9EH4c9k2o?t=205). + +**Personal MCP connections use a different authority model.** ChatGPT and other personal clients act as the authorizing user within their granted scopes and normal permissions. Their writes do not automatically enter Deft's agent approval queue. Defty and Agent Employees use agent identities and policy-based approval flows. See [MCP access and agents](docs/self-hosting.md#mcp-access-and-agents). ![A live Deft workspace](docs/assets/repository/dashboard.png) @@ -90,80 +137,16 @@ The Connections page guides each user through the setup required by their client | AI is tied to one vendor or sidebar | Teams can use Defty, Codex, Claude, ChatGPT, or their own agent runtime | | SaaS data and behavior are controlled by a vendor | The product is self-hostable and open source under AGPL-3.0-only | -## Quick start with Docker - -### Requirements - -- Docker Desktop or Docker Engine with Compose -- A machine capable of running PostgreSQL, the API, and the web app -- Optional: an AI provider key or local model endpoint for agent features - -```bash -git clone https://github.com/Maneek21/Deft.git -cd Deft -cp .env.example .env -``` - -Set the four required secrets in `.env`: - -| Variable | Generate with | -|---|---| -| `POSTGRES_PASSWORD` | `openssl rand -hex 32` | -| `JWT_SECRET` | `openssl rand -hex 32` | -| `JWT_REFRESH_SECRET` | `openssl rand -hex 32` | -| `ENCRYPTION_KEY` | `openssl rand -hex 32` | - -Then build, start, initialize, and verify the stack: - -```bash -docker compose build deft init doctor smoke -docker compose up -d -docker compose run --rm init -docker compose run --rm doctor -docker compose run --rm smoke -``` - -Open [http://localhost:3000](http://localhost:3000). The first account creates and owns the workspace. - -See [docs/self-hosting.md](docs/self-hosting.md) for environment variables, HTTPS, backups, health checks, AI providers, and production operations. - -### Run a named preview image - -Preview releases also publish an amd64 image to GHCR. Download the release -assets, copy `default.env.example` to `.env`, set the required secrets and public -URLs, then run: - -Choose a release whose notes identify it as `AGPL-3.0-only`, then set its -exact immutable tag. Historical releases through `v0.2.0-preview.4` retain the -BSL 1.1 license included in those revisions; relicensing this source tree does -not retroactively change old tags or images. - -```bash -export DEFT_IMAGE=ghcr.io/maneek21/deft:0.3.0-preview.15 -docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml pull -docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml up -d postgres -docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml run --rm init -docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml up -d deft -docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml run --rm doctor -``` - -Fresh installs use `init`. The supported versioned upgrade baseline starts at -`v0.2.0-preview.1`; later releases can be applied with the backup-first -`pnpm selfhost:upgrade --prod --release` flow documented in the self-hosting -guide. Historical pre-preview databases are not automatically adopted. - -> `pnpm db:push-full` is for fresh installs. `pnpm db:upgrade` is for supported release-to-release upgrades. Do not use raw `pnpm db:migrate` against important data. - ## Local development -Requirements: Node.js 22.13+, pnpm, and PostgreSQL 16 with pgvector. +Requirements: Node.js 22.13+, the pnpm version pinned in `package.json`, and a running PostgreSQL 16 database with pgvector. Set the four secrets in `.env` and `DATABASE_URL` for your disposable development database before initialization; see [Contributing](CONTRIBUTING.md). ```bash git clone https://github.com/Maneek21/Deft.git cd Deft pnpm install cp .env.example .env - +# Set the four secrets and DATABASE_URL before continuing. pnpm db:push-full pnpm db:seed pnpm dev @@ -187,6 +170,7 @@ deft/ | `-- api/ Hono, Socket.io, PostgreSQL job workers, agent and MCP runtime |-- packages/ | |-- db/ PostgreSQL, pgvector, Drizzle schema and migrations +| |-- mcp/ Shared MCP protocol support | `-- shared/ Shared types, schemas, and constants |-- docker-compose.yml `-- pnpm-workspace.yaml @@ -199,7 +183,7 @@ deft/ | Data | PostgreSQL 16, pgvector, Drizzle ORM | | Realtime | Socket.io in-process (single app instance) | | Jobs | PostgreSQL `job_queue` and in-process workers | -| Auth | better-auth with JWT and refresh tokens | +| Auth | Email/password with bcrypt, JWT access tokens, and refresh tokens | | AI | Provider-neutral routing plus MCP | | Storage | Local disk with R2-compatible paths | | Monorepo | pnpm workspaces | diff --git a/docs/current-limitations.md b/docs/current-limitations.md index 1f4fc110..d13f09e0 100644 --- a/docs/current-limitations.md +++ b/docs/current-limitations.md @@ -2,6 +2,8 @@ Last reviewed September 8, 2026. The latest published preview is `v0.3.0-preview.15`, a core release. +Installation and agent boundary notes updated September 11, 2026. + Deft is an alpha. It is suitable for technical evaluation, internal use, and controlled pilots where an operator can tolerate breaking changes and investigate failures. ## Installation and upgrades @@ -15,6 +17,7 @@ Deft is an alpha. It is suitable for technical evaluation, internal use, and con automatic downgrade. Operators should pin an image digest, back up Postgres and uploads, and rehearse restoring both with the previous image digest before updating. +- Content exports are partial (wiki, notes, calendar); recovery requires database, uploads, and configuration backups. ## Deployment contract @@ -26,9 +29,13 @@ Deft is an alpha. It is suitable for technical evaluation, internal use, and con ## AI and agents -- Core workspace features run without an AI provider; agent features do not. +- Core workspace features run without a Deft AI provider. Defty reasoning needs one; personal MCP clients can use their own AI provider. +- Personal MCP clients act as the authorizing user; their writes do not automatically enter the Agent Employee approval queue. See [identity and approval boundaries](self-hosting.md#identity-approvals-and-action-history). +- Knowledge summaries can be wrong or outlive a correction to their source; review and correct durable knowledge and resulting tasks. +- Self-hosted storage does not imply local AI processing: configured providers and permitted external clients can receive workspace content. See [AI data flow](self-hosting.md#ai-data-flow). - Model output is probabilistic. Deft validates structured drafts and applies permission and approval rules, but cannot guarantee perfect interpretation. - Agent employees require a separately operated compatible runtime. Deft does not host every external runtime or tool. +- A seeded demo identity is not proof of a live Hermes integration. Preview.15 is a core release without new Hermes certification. - A healthy token or connection does not guarantee that an external runtime is online, subscribed, or able to finish assigned work. - Autonomous behavior remains bounded by scopes, trust, approvals, action caps, provider availability, and customer configuration. diff --git a/docs/self-hosting-vps-domain-https.md b/docs/self-hosting-vps-domain-https.md index 9020107d..2542f113 100644 --- a/docs/self-hosting-vps-domain-https.md +++ b/docs/self-hosting-vps-domain-https.md @@ -48,7 +48,7 @@ Generate required secrets: openssl rand -hex 32 # POSTGRES_PASSWORD openssl rand -hex 32 # JWT_SECRET openssl rand -hex 32 # JWT_REFRESH_SECRET -openssl rand -base64 24 | cut -c1-32 # ENCRYPTION_KEY, exactly 32 chars +openssl rand -hex 32 # ENCRYPTION_KEY, at least 32 characters ``` Set the public URLs in `.env`: diff --git a/docs/self-hosting.md b/docs/self-hosting.md index 5e56bddc..c05d0d55 100644 --- a/docs/self-hosting.md +++ b/docs/self-hosting.md @@ -6,7 +6,9 @@ operator tasks for a self-hosted Deft workspace. ## Overview Self-hosted Deft is a single-workspace deployment. You run the PostgreSQL -database and application stack yourself. Your data stays on your infrastructure. +database and application stack yourself. Workspace storage is on your infrastructure; +configured AI providers and external clients can receive workspace content as +described under [AI data flow](#ai-data-flow). Each deployment supports one organisation. The first user to sign up becomes the workspace owner; everyone else joins through invite links generated from @@ -25,31 +27,44 @@ Redis and BullMQ are not runtime dependencies. See the | Requirement | Notes | |---|---| -| Docker Desktop 4.x+ | Includes Docker Compose v2 | +| Docker Desktop or Docker Engine | A running Linux container engine and Compose v2 | | openssl | Used to generate secrets; ships with macOS, Linux, Git for Windows | | AI provider | Optional; configure later from Settings -> AI | -The stack runs comfortably on 2 vCPU / 4 GB RAM for small pilots. +Start with 2 vCPU / 4 GB RAM for a small evaluation and measure resource use on +your workload. This is a starting configuration, not a capacity guarantee. +Commands below use Bash; Windows users can use Git Bash with Docker Desktop. ## First Boot -### Choose source build or named release +### Recommended: prebuilt release -The source-build path below is the most flexible option for contributors. -Tagged preview releases also publish an amd64 image to +For a fresh evaluation, follow the [README quick start](../README.md#quick-start-with-docker), +which pins `v0.3.0-preview.15` and its image digest. Use that release's own Compose +files and environment template together; this source checkout can differ from +the published image. The source-build instructions below are for contributors. +Tagged preview releases publish an amd64 image to `ghcr.io/maneek21/deft`. The release image injects `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_API_URL`, and `NEXT_PUBLIC_WS_URL` when the container starts, so the same image works on localhost or a custom domain. For a named release, download `docker-compose.yml`, `compose.prod.yml`, `compose.release.yml`, `default.env.example`, `self-hosting.md`, -`release-manifest.json`, and `SHA256SUMS` from the GitHub release into one -directory. Copy `default.env.example` to `.env`, then set: +`release-manifest.json`, and `SHA256SUMS` from the selected GitHub release into +a new directory. Copy +`default.env.example` to `.env`. Generate separate values with `openssl rand -hex 32` +for **all four** required secrets: `POSTGRES_PASSWORD`, `JWT_SECRET`, +`JWT_REFRESH_SECRET`, and `ENCRYPTION_KEY`. Docker runs in production mode even +on localhost. Set the image in `.env` (the tag has no leading `v`): ```bash -DEFT_IMAGE=ghcr.io/maneek21/deft: +DEFT_IMAGE=ghcr.io/maneek21/deft:0.3.0-preview.15 ``` +For another host or port, set `NEXT_PUBLIC_APP_URL`, `NEXT_PUBLIC_API_URL`, +and `NEXT_PUBLIC_WS_URL` to the browser-reachable URLs first. Keep their defaults +for localhost ports 3000/3001. Leave provider keys empty for a basic evaluation. + Use the release overlay in every application/tool command: ```bash @@ -86,6 +101,12 @@ cosign verify "$IMAGE@$DIGEST" \ gh attestation verify "oci://$IMAGE@$DIGEST" --repo Maneek21/Deft ``` +Verify downloaded assets against `SHA256SUMS`; older checksum files may name +`default.env.example` as `.env.example`, so verify the unedited template under +that name before copying it to `.env`. Do not compare your secret-filled `.env` +against the template checksum. Image verification above additionally requires +`jq`, Cosign, Docker Buildx, and GitHub CLI. + Compare `DIGEST` with `release-manifest.json` and verify every downloaded asset against `SHA256SUMS`. For a Hermes-certified release, also confirm the manifest's Hermes archive and certificate digests before extracting the integration. That @@ -97,12 +118,18 @@ SBOM and corresponding source. Then set `DEFT_IMAGE` to the immutable Versioned release upgrades begin at `v0.2.0-preview.1` and use the dedicated `upgrade` service described below. -### Fast path: one-command bootstrap +Preview.15 is a core release and carries no new Hermes certification or +integration bundle; a configured employee identity is not proof of a running +external runtime. + +### Source checkout: bootstrap wrapper If you are working from a cloned repo with Node.js and pnpm available on the -host, use the bootstrap wrapper: +host, first complete the clone and configuration step below, then use the +bootstrap wrapper: ```bash +pnpm install --frozen-lockfile pnpm selfhost:bootstrap ``` @@ -146,6 +173,9 @@ openssl rand -hex 32 # paste into JWT_REFRESH_SECRET openssl rand -hex 32 # paste into ENCRYPTION_KEY ``` +All four are required for Docker, including local evaluation. `ENCRYPTION_KEY` +must be a unique, non-placeholder secret of at least 32 characters. + Leave `OLLAMA_URL` commented unless an Ollama server is actually running. Otherwise Deft will correctly show AI features as off until a provider is configured. @@ -167,13 +197,15 @@ Corresponding Source you run, including the scripts needed to build and install it. The in-product `/license` page presents this link to users. If signup or login shows "Failed to fetch", the browser is probably trying to -call the wrong API URL. Fix the `NEXT_PUBLIC_*` values and rebuild. +call the wrong API URL. Fix the `NEXT_PUBLIC_*` values. Rebuild source images; +for prebuilt releases, recreate the app container with `up -d --force-recreate deft` +and the same three Compose files so startup injects the new URLs. ### 2. Start the stack ```bash docker compose build deft init doctor smoke -docker compose up -d +docker compose up -d postgres ``` This builds the app and one-shot tool images, then starts Postgres with pgvector. @@ -192,6 +224,11 @@ docker compose run --rm init The init service first refuses any database that already contains application tables, then runs `pnpm db:push-full && pnpm db:seed` inside the Deft image. No host Node.js or pnpm install is required for the Docker self-host path. +After successful initialization, start the app: + +```bash +docker compose up -d deft +``` `db:push-full` enables the `vector` extension, syncs the schema, and applies the supplemental SQL files for search indexes and safe metadata backfills that @@ -222,7 +259,9 @@ exercise an authenticated MCP `tools/list` call, set `DEFT_MCP_BEARER_TOKEN` in ### 5. Open the app Open `http://localhost:3000`, create the first account, and keep that account as -the owner/admin seat. +the owner/admin seat. Post a message in a space, then create and update a task. +Doctor and smoke check infrastructure and connector protocol behavior; they do +not prove first login, chat, task creation, or a model-driven approval flow. ## Fresh Reset For A Pilot Or Internal Workspace @@ -287,8 +326,9 @@ For production, use the overlay that does not publish Postgres to host ports: ```bash docker compose -f docker-compose.yml -f compose.prod.yml build deft init doctor smoke -docker compose -f docker-compose.yml -f compose.prod.yml up -d +docker compose -f docker-compose.yml -f compose.prod.yml up -d postgres docker compose -f docker-compose.yml -f compose.prod.yml run --rm init +docker compose -f docker-compose.yml -f compose.prod.yml up -d deft docker compose -f docker-compose.yml -f compose.prod.yml run --rm doctor docker compose -f docker-compose.yml -f compose.prod.yml run --rm smoke ``` @@ -387,6 +427,60 @@ the same authority model. Use personal tokens when a human wants their own AI assistant to help with work. Use agent employee tokens when an autonomous or semi-autonomous runtime should show up as a shared coworker in Deft. +### Identity, approvals, and action history + +Personal ChatGPT and other MCP connections act as the authorizing user. Scopes +limit available tools; handlers also enforce the user's organization, role, +membership, and resource access. Personal native writes execute under that user +and do **not** automatically enter the Agent Employee approval queue. A personal +client with `write:workspace` can also exercise the user's permitted approval +actions, so grant that scope deliberately. + +Defty and Agent Employees use agent identities. The API routes governed writes +through tool tiers and trust policy, then resolves required approvals on the +server. In the shared tier policy, Conservative auto-executes `auto` actions, +Standard also permits `quick`, and Autonomous also permits `full` except guarded +destructive/admin operations. Individual workflows can require stricter review. +Task creation is normally `quick`; posting a message is `full`. A task proposal +in the walkthrough is not a promise that every configured task write pauses. + +The resolver checks review authority and action state and claims pending work +before execution. Repeated approval of a completed action returns its existing +state. Idempotency and stale-target checks vary by tool; do not assume global +exactly-once execution or that every intervening edit invalidates a proposal. +Inspect the proposed details and current target before approving. + +Personal token/grant revocation blocks subsequent authenticated calls. It does +not undo completed writes or withdraw content already read by an external client. +Governed agent actions use signed receipts; personal MCP calls have OAuth/MCP +audit history. Receipts use a deployment-held HMAC secret, not independent +third-party proof. Receipt recording can fail after a write succeeds, so inspect +the resulting record and operational logs when reconciling an uncertain result. + +### Knowledge and AI data flow + +Knowledge capture stores durable wiki records and source citations. Visibility +is scoped to the organization and, for restricted pages, the owner or space +membership. A source link is evidence to inspect, not a guarantee that an AI +summary is correct. Correct the durable knowledge record as well as the source +when needed; do not assume editing a chat message rewrites every derived page or +already-created task. Wiki editing and version history support human correction. + +#### AI data flow + +With a provider enabled, classification/extraction can send chat content to the +configured model, and Defty can send prompts, retrieved messages, tasks, knowledge, +and tool results needed for a request. Embedding and transcription features can +send text or audio to their separately configured providers. Personal MCP clients +and external employee runtimes receive the records returned by their permitted +tools and have their own provider, retention, and cost policies. Self-hosting the +workspace does not by itself keep model traffic local. + +Without a Deft AI provider, normal chat, tasks, notes, manual knowledge editing, +calendar, and auth remain usable. Model-driven extraction and Defty reasoning +need a provider; deterministic capture paths may still run. A personal MCP client +can supply its own AI independently of Deft's provider configuration. + ## Environment Variables | Variable | Required | Purpose | Default | @@ -394,7 +488,7 @@ semi-autonomous runtime should show up as a shared coworker in Deft. | `POSTGRES_PASSWORD` | Yes | Database password for Compose Postgres | none | | `JWT_SECRET` | Yes | Signs access tokens | none | | `JWT_REFRESH_SECRET` | Yes | Signs refresh tokens | none | -| `ENCRYPTION_KEY` | Production | Encrypts provider keys at rest; at least 32 chars | dev value | +| `ENCRYPTION_KEY` | Yes for Docker/production | Encrypts stored credentials and signs receipts; at least 32 characters, unique and non-placeholder | none suitable for Docker | | `DEFT_APPS_ENABLED` | No | Exact `true` enables the experimental Apps API; keep aligned with the web build flag | `false` | | `NEXT_PUBLIC_FEATURE_APPS` | No | Build-time public flag that exposes Apps in the web bundle; changing it requires rebuilding the image | `false` | | `DEFT_APP_RUNS_ENABLED` | No | Exact `true` enables the App Run runtime and draining; invalid or missing keyrings then fail startup | `false` | @@ -588,6 +682,13 @@ export COMPOSE_PROJECT_NAME=deft docker compose -f docker-compose.yml -f compose.prod.yml -f compose.release.yml start deft ``` +### Content exports + +Available exports include wiki JSON/Markdown/CSV (`GET /api/wiki/export`, with +`format=md` or `format=csv`), note Markdown download, and calendar ICS feeds. +These are content exports, not a complete restorable workspace archive. Use +Postgres, uploads, and configuration backups for recovery. + ## Upgrading The first supported versioned schema baseline is `v0.2.0-preview.1`. The