SixSentences

An open research workspace for evidence, data, interviews, and writing.

Keep sources, transformations, decisions, and generated work inspectable—from the first search to the final manuscript.

Website  ·  Hosted workspace  ·  Self-host  ·  Contribute  ·  Discuss

[!WARNING] v0.2.0-alpha.1 is an early self-hosting release. APIs, migrations, and UI contracts can change before 1.0. Inspect outputs and validate methods; software cannot guarantee an exhaustive search or a scientifically valid conclusion.

Research, end to end

SixSentences brings the working parts of a research project into one traceable workspace:

The community edition is a complete application stack: a Next.js workspace, FastAPI service, PostgreSQL database, background worker, Caddy edge proxy, Manifest V3 browser-capture client, typed Python research engine, and source for the native macOS Companion. No customer data, production configuration, provider credential, or signed native binary is bundled.

Quick start

Requirements: Docker Engine and Docker Compose 2.33.1 or newer. Local mode uses loopback-only public origins; use the documented TLS mode and host firewalling before accepting real users or research data.

git clone --depth 1 https://github.com/SixSentences/sixsentences.git
cd sixsentences
make up

Open http://localhost and sign in.

make up runs deploy/community/quickstart.sh: it writes a private local configuration, runs the fail-closed preflight, builds the images, starts the stack health-gated, and prompts once for the first owner account. That last step matters — self-signup is off until you configure mail, so without an owner account nobody can sign in. The script never overwrites an existing configuration and prints no secret value.

A tagged release also publishes the two images, so a deployment can skip the build entirely:

RELEASE=v0.2.0-alpha.1  # the tag you are deploying, from the releases page
export SIX_API_IMAGE=ghcr.io/sixsentences/community-api:$RELEASE
export SIX_WEB_IMAGE=ghcr.io/sixsentences/community-web:$RELEASE-localhost
make up

The web client bakes its public origin at build time, so the published web image serves http://localhost only; a public TLS deployment builds its own with make build-up.

bash deploy/community/init-env.sh --local
bash deploy/community/preflight.sh .env.selfhost
docker compose --env-file .env.selfhost up --build --detach --wait
docker compose --env-file .env.selfhost run --rm api \
  six-community auth create-owner --email you@example.org --org "My Lab"

Read the self-hosting guide before enabling registration, mail, external models, web search, or spoken interviews, and read the backup and restore runbook before storing user data. make help lists the other deployment shortcuts.

macOS users can also build the source-only Companion against the same deployment. It adds local Apple Speech for spoken live interviews and brainstorming plus native paper chat; the Docker quick start does not build or install a macOS app.

Architecture

flowchart LR
    B[Browser] -->|HTTPS| C[Caddy]
    M[macOS Companion] -->|HTTPS · derived /api| C
    C --> W[Next.js web]
    C --> A[FastAPI API]
    A --> P[(PostgreSQL)]
    A --> D[(Application files)]
    Q[Background worker] --> P
    Q --> D
    X[Browser Capture] -->|pair and save| A
    A --> E[Research engine]
    Q --> E
    E -. operator-enabled .-> O[Metadata, mail, model, speech, and parser providers]

src/sixsentences/       Python research engine and CLI
services/api/           Application API, migrations, worker, and tests
apps/web/               Next.js research workspace
apps/browser-extension/ Self-hostable Chromium capture client
apps/companion-macos/   Native Companion source, tests, and local bundle script
deploy/community/       Self-hosting, quick start, preflight, backup, and restore
compose.yaml            PostgreSQL + API + worker + web + Caddy
Makefile                Deployment shortcuts (make help)

Outbound services are optional and use only credentials supplied by the operator. Billing, checkout, subscriptions, hosted-service administration, the production deployment, and the marketing website are intentionally not part of this repository.

Development

Use the committed lockfiles and the exact component checks:

# Python engine
uv sync --frozen --group dev
uv run ruff check . && uv run mypy src/sixsentences && uv run pytest -q

# API
uv sync --project services/api --frozen --all-groups
uv run --project services/api pytest services/api/tests

# Web
(cd apps/web && npm ci && npm run typecheck && npm test && npm run build)

# Browser extension
(cd apps/browser-extension && npm ci && npm test && \
  APP_ORIGIN=https://research.example.org \
  API_ORIGIN=https://research.example.org/api \
  node scripts/build.mjs --out /tmp/sixsentences-extension)

# macOS Companion (on macOS with Xcode 16)
bash apps/companion-macos/Scripts/audit-community-source.sh
swift test --package-path apps/companion-macos --disable-sandbox

The CI workflow also validates the application contract, self-hosting boundary, container builds, macOS Companion source, DCO sign-offs, dependency changes, CodeQL results, and secret and configuration scans. See CONTRIBUTING.md for the full local gate and pull-request expectations.

Contributing and security

Focused issues and pull requests are welcome. Contributions require per-commit Developer Certificate of Origin 1.1 sign-off and a fresh public acceptance of the repository CLA on each pull request. The local workflow uses no external CLA service or separately stored secret. Decisions and maintainer responsibilities are described in GOVERNANCE.md.

Starting out: the good first issue label collects work that is finishable without knowing the rest of the system, and each of those issues names the files to change and how to check the result. Comment /claim on one to take it, so nobody builds the same thing twice.

Report vulnerabilities through the repository's private advisory form, never through a public issue. See SECURITY.md.

License

Code and documentation are available under the Apache License 2.0, except where a file says otherwise. Dependencies and adapted components retain their own terms; see THIRD_PARTY_NOTICES.md. The SixSentences name and visual identity are protected marks; see TRADEMARKS.md.