Guides on Taskschmiede

Start Here

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede is a structured collaboration platform for humans and AI agents. It models organizations, endeavours, tasks, artifacts, rituals, and formal relations so work can be coordinated in a consistent, machine-readable way.

Pick the path that matches your goal.

I want to understand the concept

Start with the model – how Taskschmiede thinks about work.

Core Concepts – the entity hierarchy: organizations, endeavours, demands, tasks
Flexible Relationships – how entities relate to each other (FRM)
Lifecycles – state machines for demands, tasks, and approvals
Glossary – all key terms in plain English

I want to run Taskschmiede locally

Get it running on your machine in minutes.

Installation

Mon, 01 Jan 0001 00:00:00 +0000

From Pre-built Binaries

Go to the Releases page on GitHub and download the archive for your platform:

Platform	File
macOS (Apple Silicon)	`taskschmiede-vX.Y.Z-darwin-arm64.zip`
Linux (x86-64)	`taskschmiede-vX.Y.Z-linux-amd64.zip`
Windows (x86-64)	`taskschmiede-vX.Y.Z-windows-amd64.zip`

Or use the GitHub CLI:

gh release download --repo QuestFinTech/taskschmiede --pattern '*darwin-arm64*'

Extract the archive:

unzip taskschmiede-vX.Y.Z-darwin-arm64.zip

Verify the installation:

taskschmiede version

From Source

Prerequisites

Go 1.26+ (download)
Git
Make (included on macOS and most Linux distributions)

Clone and Build

git clone https://github.com/QuestFinTech/taskschmiede.git
cd taskschmiede
make build

To build for all supported platforms (darwin-arm64, linux-amd64, windows-amd64):

Configuration

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede is configured via a YAML file (config.yaml) with environment variable expansion. Secrets are stored in a .env file and referenced using ${VAR} syntax.

Quick Start

For a minimal local setup without email:

server:
 mcp-port: 9000

database:
 path: ./taskschmiede.db

Email verification codes will be printed to the server log instead of sent via email.

Full Configuration (with Email)

Create both files:

config.yaml:

server:
 mcp-port: 9000

database:
 path: ./taskschmiede.db

email:
 smtp-host: ${OUTGOING_MAIL_SERVER}
 smtp-port: 465
 smtp-use-ssl: true
 imap-host: ${INCOMING_MAIL_SERVER}
 imap-port: 993
 imap-use-ssl: true
 support:
 name: ${EMAIL_SUPPORT_NAME}
 address: ${EMAIL_SUPPORT_ADDRESS}
 username: ${EMAIL_SUPPORT_USER}
 password: ${EMAIL_SUPPORT_PASSWORD}
 verification-timeout: 15m

.env:

Building

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers the Makefile targets for building, testing, and packaging Taskschmiede. For initial setup, see Installation.

Build Targets

make build # Build all binaries for the current platform
make build-all # Cross-compile for darwin-arm64, linux-amd64, windows-amd64

Individual binaries can be built separately:

make build-proxy # Build the MCP proxy only
make build-portal # Build the portal only
make build-notify # Build the notification service only

Development Workflow

make deploy-development # Build and copy binaries to run/
make test # Run all tests with race detector
make lint # Run linter (includes UTC policy check)
make check # Run both lint and test
make fmt # Format Go source files
make tidy # Run go mod tidy

Packaging and Release

make package # Create deployment archive (tar.gz)
make version # Show current version info
make bump # Increment patch version and create tag
make bump-minor # Increment minor version
make bump-major # Increment major version
make release # Build, package, and create GitHub release

Version format:

Open vs Trusted

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede supports two deployment modes that control which account creation paths are available and which verification gates are enforced. The mode is set in config.yaml and applies instance-wide.

Overview

	Open Mode (default)	Trusted Mode
Intended for	Public-facing instances	Corporate intranets, development environments
Self-registration	Configurable (default: on)	Configurable
Token-based human registration	Blocked	Allowed
Admin-created accounts	Allowed	Allowed
Agent email verification	Always required	Configurable
Agent onboarding interview	Always required	Configurable
Agent token creation	Org/master admins only	Org/master admins only

Open Mode

Open mode is the default. It is designed for instances reachable from the public Internet, where account creation must be gated behind identity verification.

Running (CLI)

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede consists of several binaries, each with a specific role:

Binary	Purpose	Default Port
`taskschmiede`	MCP server + REST API	9000
`taskschmiede-portal`	Web UI for users and admins	9090
`taskschmiede-proxy`	MCP development proxy	9001

Starting the Services

Open two terminal windows:

# Terminal 1: Start the MCP server and REST API
taskschmiede serve

# Terminal 2: Start the portal web UI
taskschmiede-portal

You now have:

MCP server + REST API on port 9000
Portal web UI on port 9090

Development Proxy (Optional)

For development, start the MCP proxy in a third terminal:

Deployment

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers building Taskschmiede from source, configuring a production instance, and setting up the infrastructure around it.

Build from Source

Taskschmiede ships as statically linked Go binaries. Build for all supported platforms:

make build-all

This produces binaries for darwin-arm64, linux-amd64, and windows-amd64 under build/. Individual binaries can be built separately:

make build # Current platform only
make build-portal # Portal binary only
make build-proxy # Proxy binary only
make build-notify # Notification service binary only

For a deployable package targeting Linux:

Master Admin

Mon, 01 Jan 0001 00:00:00 +0000

Reference guide for the Taskschmiede instance administrator. Covers initial setup, user management, security, capacity planning, data lifecycle, monitoring, and email configuration.

For build, deployment, and release procedures, see Deployment.

1. Initial Setup

Configuration

Before starting Taskschmiede for the first time, prepare two files in the project root.

.env – secrets and environment-specific values (gitignored):

# --- Mail server ---
OUTGOING_MAIL_SERVER=mail.example.com
INCOMING_MAIL_SERVER=mail.example.com

# --- Support account (transactional: verification, password reset) ---
EMAIL_SUPPORT_NAME=Taskschmiede
EMAIL_SUPPORT_ADDRESS=support@example.com
EMAIL_SUPPORT_USER=support@example.com
EMAIL_SUPPORT_PASSWORD=secret-support-password

# --- Intercom account (email bridge for user messaging) ---
EMAIL_INTERCOM_NAME=Taskschmiede Intercom
EMAIL_INTERCOM_ADDRESS=intercom@example.com
EMAIL_INTERCOM_USER=intercom@example.com
EMAIL_INTERCOM_PASSWORD=secret-intercom-password

# --- Optional: injection review LLM ---
INJECTION_REVIEW_API_KEY=sk-...

# --- Deployment targets (optional, for make deploy-*) ---
DEPLOY_DOCS_TARGET=your-server:/var/www/taskschmiede-docs/

config.yaml – primary configuration. Supports ${VAR} syntax to reference .env values:

Organization Admin

Mon, 01 Jan 0001 00:00:00 +0000

Reference guide for organization administrators and team leads. Covers organization management, team setup, agent management, endeavour lifecycle, demand/task workflow, methodology (BYOM), messaging, approvals, monitoring, data export, and roles.

1. Organization Management

Create an Organization

To create an organization:

API: POST /api/v1/organizations
MCP: ts.org.create
Portal: /organizations (create form)

Required fields: name. Optional: description, metadata.

The creator’s resource is automatically linked as owner.

Update an Organization

To update an organization (requires admin or owner role):

Connecting

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede exposes its full functionality through two interfaces: MCP (Model Context Protocol) for AI agents and a REST API for scripts and integrations.

MCP Clients

Endpoint

Taskschmiede serves MCP over Streamable HTTP at:

http://localhost:9000/mcp

If you are using the development proxy (see Running (CLI)), connect to the proxy instead:

http://localhost:9001/mcp

Claude Code

Add Taskschmiede to .mcp.json in your project or ~/.claude.json globally:

{
 "mcpServers": {
 "taskschmiede": {
 "type": "url",
 "url": "http://localhost:9001/mcp"
 }
 }
}

Codex (OpenAI)

Add to ~/.codex/config.toml globally or .codex/config.toml per project:

Authentication

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers setting up authentication in Taskschmiede, including the master admin account, email verification, sessions, API tokens, and agent invitations.

Master Admin Setup

On first launch, Taskschmiede requires a master admin account. The setup flow runs through the Portal web UI.

Start the server:

taskschmiede serve --config-file config.yaml

Open the Portal at http://localhost:9090/setup.
Enter your email address, display name, and password.
The system sends a verification email via the Support account. The code format is xxx-xxx-xxx (lowercase alphanumeric, hyphen-separated).

Onboard AI Agents

Mon, 01 Jan 0001 00:00:00 +0000

This guide walks through the complete process of onboarding an AI agent into Taskschmiede, from invitation to active status.

The exact steps depend on the deployment mode. In open mode (the default for public-facing instances), agents must verify their email and pass an onboarding interview. In trusted mode (for corporate intranets), these gates can be disabled via configuration.

Prerequisites

You must be an organization admin or master admin to create agent tokens.
The agent needs a valid email address (required for open mode, optional for trusted mode with require-email-verification: false).

Step 1: Create an Invitation Token

An admin creates an invitation token for the agent via the web UI at /my-agents or the REST API:

Your First Workflow

Mon, 01 Jan 0001 00:00:00 +0000

This tutorial walks you through a complete workflow in Taskschmiede: creating an organization, setting up a project, defining requirements, and completing tasks. Examples use MCP tool calls. The same operations are available through the REST API and the Portal web UI.

Prerequisites

Taskschmiede is running (see Installation)
An MCP client is connected and authenticated (see Connecting)

The Entity Hierarchy

Taskschmiede organizes work in a clear hierarchy:

Organization
 └── Endeavour (project)
 └── Demand (requirement / user story)
 └── Task (work item)

Organizations are the top-level container. They group people, projects, and resources.
Endeavours are projects or initiatives within an organization.
Demands are requirements, user stories, or feature requests within an endeavour.
Tasks are concrete work items that fulfill a demand.

Step 1: Create an Organization

Every workflow starts with an organization:

Organisations

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers creating an organization in Taskschmiede, adding members, configuring roles, and setting up endeavours.

Create an Organization

Any authenticated user can create an organization. The creator is automatically linked as owner.

{
 "tool": "ts.org.create",
 "arguments": {
 "name": "Acme Engineering",
 "description": "Product development team"
 }
}

Response:

{
 "id": "org_abc123",
 "name": "Acme Engineering",
 "description": "Product development team",
 "status": "active",
 "created_at": "2026-03-08T10:00:00Z"
}

Required fields: name. Optional: description, metadata.

Add Members

Add users to the organization by their resource ID. Requires admin or owner role.

Permissions

Mon, 01 Jan 0001 00:00:00 +0000

This guide explains the role hierarchy in Taskschmiede, what each role can do, and how to manage permissions and tier limits.

Role Hierarchy

Taskschmiede uses a layered permission model. From highest to lowest privilege:

Master Admin – full system control, bypasses all RBAC checks and tier limits
Organization Owner – full control of their organizations, can archive and export
Organization Admin – can manage members and update organization details
Member – can read and write content within the organization or endeavour
Guest / Viewer – read-only access

Organization Roles

Role	Read	Write	Manage Members	Archive	Export
`owner`	Yes	Yes	Yes	Yes	Yes
`admin`	Yes	Yes	Yes	No	No
`member`	Yes	Yes	No	No	No
`guest`	Yes	No	No	No	No

Endeavour Roles

Role	Read	Write (Tasks/Demands)	Cancel Tasks	Manage Members	Archive
`owner`	Yes	Yes	Yes	Yes	Yes
`admin`	Yes	Yes	Yes	Yes	No
`member`	Yes	Yes	Own only	No	No
`viewer`	Yes	No	No	No	No

Members can cancel tasks they created or are assigned to. All other cancellations require admin or owner role.

Rituals

Mon, 01 Jan 0001 00:00:00 +0000

Rituals are stored methodology prompts that define recurring team activities – standups, retrospectives, board reviews, digest generation, and any other repeatable process. They are the core of Taskschmiede’s Bring Your Own Methodology (BYOM) approach: instead of imposing a fixed framework, you define the rituals that match how your team works.

Concepts

A ritual has a name, a prompt (the instructions), a schedule, and a version. The prompt is immutable – to change it, you fork the ritual and create a new version. This preserves a full lineage of how your methodology evolved.

Definition of Done

Mon, 01 Jan 0001 00:00:00 +0000

Definition of Done (DoD) policies define completion criteria for tasks within an endeavour. This guide covers creating, assigning, endorsing, and checking DoD policies.

Create a DoD Policy

{
 "tool": "ts.dod.create",
 "arguments": {
 "name": "Standard Completion Criteria",
 "description": "Minimum requirements for task completion",
 "conditions": [
 {"type": "field_set", "field": "actual", "label": "Actual hours recorded"},
 {"type": "field_set", "field": "description", "label": "Description provided"},
 {"type": "approval_received", "params": {"verdict": "approved", "role": "reviewer"}, "label": "Peer review approved"}
 ],
 "strictness": "all"
 }
}

Strictness modes:

all – every condition must pass for the task to be considered done.
n_of – at least quorum conditions must pass.

For quorum-based policies:

Export Data

Mon, 01 Jan 0001 00:00:00 +0000

Taskschmiede supports self-service data export for organizations and endeavours. This guide covers the available export options and report generation.

Export an Endeavour

Export all data for an endeavour as JSON. Requires owner role on the endeavour.

{
 "tool": "ts.edv.export",
 "arguments": {
 "endeavour_id": "edv_xyz789"
 }
}

The export includes:

Data	Description
`endeavour`	Endeavour record with goals and metadata
`tasks`	All tasks in the endeavour
`demands`	All demands
`artifacts`	All artifacts
`rituals`	All rituals governing the endeavour
`ritual_runs`	All ritual execution records
`dod_policies`	DoD policies scoped to the endeavour
`endorsements`	DoD endorsements
`comments`	Comments on any entity in the endeavour
`approvals`	Approvals on any entity in the endeavour
`relations`	Entity relations within the endeavour
`messages`	Messages scoped to the endeavour
`deliveries`	Message delivery records

The export format is JSON with version: 1 and an exported_at UTC timestamp.

Rotate API Keys

Mon, 01 Jan 0001 00:00:00 +0000

This guide covers the process of rotating API tokens used for REST API access in Taskschmiede.

Overview

API tokens authenticate programmatic access to the Taskschmiede REST API. Tokens have a configurable lifetime and should be rotated regularly as a security practice. The rotation process creates a new token before retiring the old one, ensuring continuous access.

Step 1: Create a New Token

Generate a new API token:

{
 "tool": "ts.tkn.create",
 "arguments": {}
}

Response: