Seyal is open source under AGPL-3.0 when the source is published. Read the self-host guide
seyal
Menu
Back to Seyal

Run Seyal on your own server.

Give Claude Code, Codex and other MCP agents a shared task board. Keep the criteria, evidence and completion check on infrastructure you control.

The source is not public yet. This is what setup will look like.

A locked glass server stack sits inside a glass box.

What you need

  • Docker (Compose runs a local Postgres 16; in production any Postgres 16).
  • Node 22; run corepack enable to get the pinned pnpm.
  • Git and a server you control.
  • A Microsoft Entra ID app registration for sign-in.
  • A domain and HTTPS for an installation your team can reach.

Quick start

Replace <repository-url> with the public clone URL when it is available. These commands prepare a checkout and start the database.

TerminalShell
git clone <repository-url> seyal
cd seyal
cp .env.example .env
pnpm install

# Edit .env with your settings.
docker compose up -d db

Database commands read DATABASE_URL from the shell first, then the repo root .env beside pnpm-workspace.yaml. After editing .env, run migrations directly:

pnpm db:migrate

The root Compose file starts Postgres only. Wait for it to be healthy before running migrations. The bundled database listens on 127.0.0.1 only, and its credentials are for local use; configure private access, credentials and backups for your server.

Start a local checkout

To try locally without Microsoft 365, set NODE_ENV=development and DEV_SIGN_IN_AS=person:<id> in .env. Replace <id> with a local person identifier. Start the API and web app:

pnpm dev

The API runs on port 8787 and the web app on port 5173.

Run in production

Set production values in .env, including a DATABASE_URL reachable from the container. Apply migrations to that database before starting. NODE_ENV defaults to production, which turns on sign-in rate limits and refuses development sign-in.

docker build -t seyal .
docker run --env-file .env \
  -p 8787:8787 seyal

Put an HTTPS reverse proxy (for example Caddy) in front of port 8787.

The container does not run migrations on start by default. Set RUN_MIGRATIONS=true to apply them on startup; otherwise run pnpm db:migrate from the checkout with your production DATABASE_URL and NODE_ENV=production in the root .env or the shell. This also applies to pnpm db:generate, pnpm db:seed and pnpm db:import:commerce. A missing DATABASE_URL in production fails with a message naming .env.example; only outside production do database commands use the local default.

Set up your installation

Database
Set DATABASE_URL to your Postgres 16 connection. Run migrations against that database.
Server address
Set PUBLIC_URL to your HTTPS address and use NODE_ENV=production for a hosted installation.
Sign-in
Set BETTER_AUTH_SECRET, MICROSOFT_TENANT_ID, MICROSOFT_CLIENT_ID and MICROSOFT_CLIENT_SECRET. Configure the Entra app for your host.
Ownership
Set SEYAL_OWNER_EMAILS for your installation; the server will not start in production without it. Keep development sign-in disabled on a hosted server.
Allowed email domains
Optionally set SEYAL_ALLOWED_EMAIL_DOMAINS to a comma-separated list of email domains allowed to sign in. Matching is case-insensitive.
Trusted proxy
SEYAL_TRUST_PROXY defaults to false. Enable it only behind a proxy that overwrites X-Forwarded-For, and block direct server access. Seyal then trusts the first address in that header.
Agent access
Connect your MCP client to https://your-host/mcp. Agents use the same completion check as everyone else. Create a token limited to your projects with Connect a device in Settings → Connections; owners also manage client tokens in Settings → MCP & access. Set SEYAL_URL to your own MCP address before using seyal init or the stdio bridge; neither chooses a server for you. Connect your MCP client.

Keep secrets in environment variables, outside source control. The repository's .env.example describes the available settings.

Where your data goes

Your tasks, evidence and event history live in your installation. You manage access, updates and backups.

Sign-in uses Microsoft Entra ID. Optional features send data to the provider you configure: an AI provider (Anthropic, OpenAI, Google or Azure OpenAI), WhatsApp, email through Microsoft 365, and GitHub or Azure DevOps webhooks. Optional integrations require their credentials and configuration. Read the security and data guide.

Fonts load from Google Fonts.

Open source under AGPL-3.0 when the source is published.

The clone command is a placeholder until the source is published.