A Configurable and Traceable Environment for Human-AI Collaborative Writing.

Product · Features · Self-Host · Development · Architecture

Humanly is a writing provenance platform for human-AI collaboration. Writers draft inside an owner-configured environment while Humanly records the process as it happens. The resulting certificate lets readers inspect how the document was produced instead of inferring authorship from the final text alone.

Product

Humanly has two first-party web apps and a public certificate surface:

• Writer Portal: app.writehumanly.net for personal writing, assigned tasks, PDF-backed writing, AI-assisted drafting, submissions, and certificates.
• Publisher Portal: admin.writehumanly.net for creating tasks, configuring writing environments, distributing share links, reviewing submissions, and inspecting certificates.
• Certificate verification: shareable certificate URLs expose only the display fields selected by the certificate owner and verify the integrity seal attached to the record.

Features

• Configurable writing environments for personal writing and assigned tasks, including AI policy, copy-paste rules, timing, length bounds, writing instructions, PDF access, detectors, and assigned-task attempt rules.
• AI policy controls that can disable AI, allow only selected-text polish, allow only chat, or allow full in-platform assistance.
• Process tracing for typing, editing, copy/paste, focus, navigation, workspace activity, and in-platform AI interactions.
• Task distribution through invite codes and public share links, including account or guest participation depending on the task setting.
• Shareable certificates with authorship statistics, replay, environment settings, anomaly behavior review signals, and integrity seal details.

One Command Deployment

Create and start a full local Humanly stack without cloning the repository or installing Node.js first:

curl -fsSL https://writehumanly.net/install.sh | sh

The installer checks Docker and Docker Compose, installs them on supported hosts when possible, downloads the Humanly source code, generates local secrets, writes a Docker Compose quickstart, seeds a local Publisher Portal admin account, and starts the services. Email is local-only with EMAIL_SERVICE=console; no SMTP, SendGrid, Resend, S3, or other third-party service is required for local use.

The local stack also starts the inference service used by the Humanly Typing Detector. Private detector weights are not bundled; when model.joblib is not mounted, the stack still starts and detector requests return an inconclusive result instead of blocking local use.

Then open:

• Publisher Portal: http://localhost:3000
• Writer Portal: http://localhost:3002
• Backend API: http://localhost:3001

Default local admin account:

Email:    admin@mail.com
Password: admin123456

Manage the local stack from the generated directory:

cd humanly
./humanly status
./humanly stop
./humanly start
./humanly restart
./humanly upgrade
./humanly uninstall

To install without starting Docker immediately:

curl -fsSL https://writehumanly.net/install.sh | sh -s -- --no-start

If the website installer endpoint is unavailable, use the repository fallback:

curl -fsSL https://raw.githubusercontent.com/Humanly-Lab/humanly/main/scripts/install.sh | sh

If you already cloned this repository and want to run the checked-out code directly:

docker compose -f docker-compose.quickstart.yml up --build

For manual setup, environment variables, and persistent self-deployment notes, see docs/SELF_DEPLOY.md.

Development

Source development requires Node.js 20.19, pnpm 9, Docker, and Docker Compose.

git clone https://github.com/Humanly-Lab/humanly.git
cd humanly
corepack enable
pnpm install --frozen-lockfile
pnpm setup:local

Start the applications in separate terminals:

pnpm dev:backend        # http://localhost:3001
pnpm dev:frontend       # http://localhost:3000
pnpm dev:frontend-user  # http://localhost:3002

Run the repository quality gates before opening a pull request:

pnpm type-check
pnpm test:runnable
pnpm build:all

Architecture

Humanly is a pnpm workspace with an Express backend, a Python inference service, two Next.js apps, and shared packages for the writing editor, tracking, and cross-app types.

packages/backend        Express API, storage, events, certificates, AI
packages/inference      FastAPI model inference service
packages/frontend       Publisher Portal
packages/frontend-user  Writer Portal and writing workspace
packages/editor         Writing editor
packages/tracker        External-form tracking library
packages/shared         Shared types and utilities
packages/create-humanly Self-host installer package

Local and production deployments use PostgreSQL for durable data, Redis for cache and realtime support, file/object storage for uploaded PDFs and attachments, and optional detector weights for model inference.

Links

• Self-deployment guide: docs/SELF_DEPLOY.md
• npm installer: create-humanly
• Latest release: GitHub Releases
• Contributing: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• License: MIT