# Introduction

## What Is Knecht?

Knecht is a self-hosted dashboard that runs workflows on your projects. A workflow boots the project in an isolated environment on your server and works through a list of steps, for example a Composer update, the test suite, a link check, or an AI agent that looks into a bug report. The result comes back as a pull request, a preview URL, or a comment in the ticket that started it.

It is aimed at agencies and freelancers that maintain many projects at once. The work it takes over is the recurring kind, security and dependency updates, link checks, and the first look at a bug report, where most of the effort goes into booting the right project.

## What Knecht Is Not

- **Not an AI tool.** The AI action is one action among others. A workflow that updates packages, runs the tests, and opens a pull request needs no AI at all.
- **Not a hosting platform.** Previews exist for review, sit behind the login, and go away with the session. Production stays where it is.
- **Not a cloud service.** You need your own Linux server or a Mac, and you install and update Knecht yourself. During the beta we host a limited number of instances, see [Beta Testers](https://knecht.works/docs/resources/beta-testers).
- **Not zero-effort.** A project has to be bootable by a machine. Projects with a [DDEV](https://ddev.com){rel=""nofollow""} config qualify directly. For PHP and Node projects without one, Knecht detects the stack and generates the config.

## Features

| Feature               | Explanation                                                                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Deterministic steps   | Boot the project, run shell commands or your own JavaScript, call URLs, check links, create branches, commits, and pull requests, with conditions and loops.                            |
| AI agent              | Hands the booted project to an agent that reads code, changes files, and runs commands until the task is done. Keeps a memory per project.                                              |
| Triggers              | GitHub events, changes in an [issue tracker](https://knecht.works/docs/usage/triggers#trigger-types), a schedule, or a click in the dashboard. One workflow can serve several projects. |
| Mentions              | `@knecht-works <instruction>` in a GitHub issue or pull request, or a mention of the Knecht account in an issue tracker, continues the work where the last run stopped.                 |
| Previews              | Every session gets a URL under your domain with a real database behind it, gated by the Knecht login.                                                                                   |
| Terminal and IDE      | Open a shell, an SSH command, or VS Code in the running environment from the run page.                                                                                                  |
| Retry                 | A failed run resumes from the step where it stopped, earlier outputs are kept.                                                                                                          |
| Environment lifecycle | Idle environments are stopped, archived, and removed on schedules you set.                                                                                                              |
| Team access           | Members sign in with GitHub. An allowlist decides who gets in.                                                                                                                          |
| Workflows as code     | Export and import workflows as YAML.                                                                                                                                                    |
| Updates               | One install script, updates from the dashboard, optional auto-update.                                                                                                                   |

## Getting Started

[Concepts](https://knecht.works/docs/get-started/concepts) explains how a run works and what projects, sessions, and previews are. [Installation](https://knecht.works/docs/get-started/installation) gets the instance up, [Setup](https://knecht.works/docs/get-started/setup) creates the GitHub App and invites the team, and [Projects](https://knecht.works/docs/usage/projects) adds the first project. The pages under Integrations describe what each integration can do, starting with [GitHub](https://knecht.works/docs/integrations/github).

## Community

Knecht is young and built in the open, and the people who run it shape where it goes. If you try it, we would like to hear how it went. What worked, what broke, which workflow you wish existed, which stack refused to boot. Every report helps, and the small ones are often the most useful.

- **Discord.** The [Knecht Discord](https://discord.gg/WuxjmtgUyX){rel="&#x22;nofollow&#x22;"} is where questions get answered and ideas get discussed. Say hello, show what you built, or ask when something is unclear.
- **GitHub.** Bugs and feature requests are welcome as issues on [GitHub](https://github.com/knecht-works){rel="&#x22;nofollow&#x22;"}. The code is public.
- **Email.** For anything else, write to <hallo@knecht.works>. A real person reads it.

What changes as a result shows up on the [Updates](https://knecht.works/updates) page.


# Concepts

A trigger starts a workflow on a project. Knecht boots the project in a session, runs the steps in order, and delivers what the last steps produced. This page explains each of these pieces, in the order a run touches them, and how the environments are isolated from each other.

![A project, a GitHub issue as trigger, a session with two runs and a follow-up mention, and a pull request and preview as result](https://knecht.works/assets/knecht-concepts.png)

## Projects

A project is a GitHub repository connected to Knecht. If the repo already ships a `.ddev/config.yaml`, Knecht boots from it as it is. If not, Knecht reads `composer.json`, `package.json`, `.nvmrc`, and the lockfile, and generates the environment itself. Environment variables and a database dump are stored on the project, so every run starts from a working state.

Adding and configuring projects is covered on [Projects](https://knecht.works/docs/usage/projects).

## Workflows

A workflow is a list of steps Knecht runs on a project, in a fixed order. A typical one boots the project, updates the Composer packages, runs the tests, and opens a pull request. None of these steps need AI. Workflows live in the dashboard, and every instance ships with two starter workflows to copy from.

Building and testing workflows is covered on [Workflows](https://knecht.works/docs/usage/workflows).

## Triggers

A trigger defines when a workflow starts on its own. Knecht reacts to GitHub events such as a new issue or a label, to changes in a connected [issue tracker](https://knecht.works/docs/usage/triggers#trigger-types), and to a schedule. Any workflow can also be started by hand. One workflow can serve several projects.

## Actions

Each step in a workflow executes one action. Deterministic actions boot the project, run a shell command or your own JavaScript, call a URL, check the site for broken links, or create a branch, a commit, and a pull request. Control flow actions run steps conditionally or in a loop. The AI action hands the booted project to an agent that reads code, changes files, and runs commands until the task is done. It is one action among the others, and a workflow works without it.

The agent, its instructions, and its memory are covered on [AI Agent](https://knecht.works/docs/usage/agent).

## Sessions

A session belongs to one GitHub issue or pull request, or to one issue in a connected issue tracker. It holds the checkout, the environment, and one shared agent conversation, so a follow-up mention continues where the last run stopped instead of starting over. The session closes with the issue and revives if the issue is reopened. Events without an issue, such as a schedule or a manual start, get a session of their own that closes after the single run.

## Runs

A run is one execution of a workflow inside a session. Two triggers on the same issue run one after the other, never in parallel. A run has its own status, log, and steps, and a failed run can be retried from the step where it stopped.

![The project page with a succeeded run, the live preview in the middle, the follow-up chat below it, and the sessions and automation panels on the right](https://knecht.works/assets/knecht-run.png)

## Previews

Every session gets a preview URL. It shows the current state of the environment, stays the same across all runs of the session, and needs a Knecht login to open.

## Isolation

Every session runs in its own environment on your server. Nothing inside it can reach the host or another session.

- **Own checkout and containers.** A session gets its own clone of the repository and its own [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} project, with a separate web container, database container, and volumes. Two sessions of the same project never share files or a database.
- **Commands run inside the container.** Shell commands, JavaScript steps, the agent, the terminal, and the IDE all execute inside the session's web container as an unprivileged user. The Docker socket and the DDEV CLI stay on the Knecht side, so a step cannot start containers or touch the host.
- **Sessions cannot see each other.** The containers are detached from DDEV's shared network and attached only to Knecht's ingress network. No ports are published on the host. Previews go through Knecht's proxy, container to container, behind the login.
- **Short-lived credentials.** Git pushes from a session use an installation token that is scoped to the one repository and expires after about an hour. The AI key reaches the agent process as an environment variable, not as a file in the checkout.

## Security

On a self-hosted instance, Knecht does not manage your server's security or its updates. That stays your responsibility. On a managed instance we operate the server.

The installer sets up Docker, DDEV, and Knecht itself, nothing more. Hardening the host, keeping the operating system patched, restricting SSH, and setting up a firewall beyond ports 80 and 443 are up to you. Knecht updates itself from the dashboard, the rest of the host it leaves alone.

What Knecht does cover is the door into the instance. Sign-in goes through GitHub, only accounts on the member list get in, previews and the IDE sit behind that login, webhooks are signature-checked, and stored credentials are encrypted. Since the Knecht container drives the host's Docker daemon, the host should run nothing but Knecht.


# Installation

Knecht is installed on a server you control. One script sets up Docker, the [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} CLI, and the app itself. This page ends when the dashboard is reachable under your domain. What happens on the first visit is covered in [Setup](https://knecht.works/docs/get-started/setup).

## Requirements

### Server

A fresh server with root access, used only for Knecht. This can be:

- A VPS, for example a [Hetzner](https://www.hetzner.com/cloud){rel="&#x22;nofollow&#x22;"} CX23 or CX33
- A dedicated server or a virtual machine
- A Mac, for example a Mac mini, through a Lima VM. See [Install on macOS](https://knecht.works/#install-on-macos).

::note
Keep the host free of other Docker setups. Knecht boots the project environments on the host's Docker daemon and takes ports 80 and 443 for its own entry point.
::

### Operating System

- Ubuntu 24.04
- amd64 or arm64

The installer stops on other distributions. Other Ubuntu versions are not tested.

### Hardware

|      | Minimum | Comfortable |
| ---- | ------- | ----------- |
| RAM  | 4 GB    | 8 GB        |
| Disk | 40 GB   | 80 GB       |

Every running preview costs one web and one database container. More parallel previews need more RAM.

### Domain and Network

- A domain or subdomain for the instance, for example `knecht.example.com`
- Access to its DNS, for two records you set after the install
- Ports 80 and 443 reachable from the internet

## Install on Linux

As root on the fresh server:

```bash
curl -fsSL https://raw.githubusercontent.com/knecht-works/knecht-cloud/main/scripts/install.sh | bash
```

The installer asks for your domain and does the rest. It installs Docker and the pinned DDEV CLI, warms up the DDEV images, checks out the latest release under `/opt/knecht`, writes a `.env`, and starts the app together with the Caddy TLS entry point via Docker Compose. It takes a few minutes and is safe to re-run if something breaks halfway.

::note
For a non-interactive install, pass the domain up front with `KNECHT_DOMAIN=knecht.example.com bash`. Any further `KNECHT_*` variable, for example `KNECHT_AI_KEY`, is carried into the `.env` and locks that setting in the dashboard.
::

::steps{level="3"}
### Set the DNS Records

Two `A` records, both pointing at the server's IP:

```text
knecht.example.com
*.preview.knecht.example.com
```

The wildcard serves the preview URLs. Every session gets its own hostname below `preview`.

### Open Ports 80 and 443

Both must be reachable from the internet. On a cloud VPS this usually means a rule in the provider's firewall.

### Open the Dashboard

Visit `https://knecht.example.com`. Caddy fetches the certificate on first start, so the first request can take a moment. The page that opens is the GitHub App setup, continued in [Setup](https://knecht.works/docs/get-started/setup).
::

## Install on macOS

The run substrate, host Docker plus DDEV, is Linux only. On a Mac the same setup runs inside a [Lima](https://lima-vm.io){rel="&#x22;nofollow&#x22;"} VM. The template from the repo gives the VM 4 CPUs, 8 GB RAM, and 80 GB disk, and forwards ports 80 and 443 on all interfaces of the Mac.

::steps{level="3"}
### Create the VM

```bash
brew install lima
limactl create --name=knecht https://raw.githubusercontent.com/knecht-works/knecht-cloud/main/scripts/lima-server.yaml
limactl start knecht
```

### Run the Installer inside the VM

```bash
limactl shell knecht
curl -fsSL https://raw.githubusercontent.com/knecht-works/knecht-cloud/main/scripts/install.sh | sudo bash
```

The installer asks for the domain, the same as on Linux.

### Make the Mac Reachable

The three steps from the Linux install apply unchanged: DNS records, ports, dashboard. On a home network, two things come on top:

- Forward TCP ports 80 and 443 on your router to the Mac, and give the Mac a fixed address in the router.
- Home connections change their public IP over time. Point the two DNS records at a dynamic DNS name, or get a static IP from your ISP.
::

### After a Reboot

The VM does not start on its own. Run `limactl start knecht` after a macOS reboot, the containers inside come back up by themselves. `/opt/knecht` and `/data/knecht` live inside the VM, reachable through `limactl shell knecht`.

### Local Domain for Testing

To try Knecht on a Mac without any DNS setup, install it under a local domain. GitHub cannot reach the instance then, so webhooks never arrive and GitHub triggers do not fire. Manual and scheduled triggers work.

::steps{level="4"}
#### Use lvh.me as the domain

`lvh.me` is a public domain that, together with all its subdomains, always resolves to `127.0.0.1`. It needs no DNS setup and no entries in `/etc/hosts`. Enter `lvh.me` when the installer asks for the domain, then the dashboard and every preview subdomain work locally. Ports 80 and 443 on the Mac must be free.

#### Switch Caddy to its internal CA

Let's Encrypt cannot issue certificates for a local domain. Inside the VM, edit `/opt/knecht/Caddyfile` so both site blocks use `tls internal`:

```text
{$KNECHT_BASE_DOMAIN} {
    tls internal
    reverse_proxy knecht:3000
}

https:// {
    tls internal {
        on_demand
    }
    reverse_proxy knecht:3000
}
```

#### Restart Caddy and open the dashboard

```bash
cd /opt/knecht && sudo docker compose restart caddy
```

Open `https://lvh.me` and accept the certificate warning.
::

Once the dashboard opens, continue with [Setup](https://knecht.works/docs/get-started/setup). Updating, backups, and pre-releases are on [Maintenance](https://knecht.works/docs/get-started/maintenance).


# Setup

The first visit to a fresh instance lands on the setup page. It creates the GitHub App that Knecht signs in with and reads repositories through. This page walks through that flow, then through the settings you need before the first project: who can sign in and the AI provider. Every issue tracker has its own page under Integrations.

::tip
A community walkthrough of the installation and setup is on [Matthias Andrasch's blog](https://matthias-andrasch.eu/blog/2026/exploring-knecht-cloud-for-ddev-ai-installation-part-1/){rel=""nofollow""}.
::

## Creating the GitHub App

The setup page has one button, "Create GitHub App". Knecht does not ask for client IDs or secrets. It sends a prefilled manifest to GitHub and gets the credentials back. The app is created under the account that clicks the button, and that account becomes the owner of the instance.

::steps{level="3"}
### Confirm the App on GitHub

GitHub shows the prefilled app with the name `Knecht <your host>`. You can edit the name, everything else is set by the manifest. The app requests write access to contents, pull requests, and issues, read access to metadata, and subscribes to pull request, issue, and issue comment events. Submit the form.

### Install the App on Your Repositories

GitHub hands the credentials to Knecht, which stores them encrypted and sends you straight to the installation page. Pick the account or organization, then either all repositories or a selection. The app is public, so it can be installed on any organization you administer, not only on the account that created it. Repositories can be added later in the app's settings on GitHub.

### Sign In

After the installation, GitHub redirects to the login page of your instance. Sign in with GitHub. The same app handles login, so there is no separate OAuth setup. You land in the dashboard as the owner.
::

::note
The setup runs once. When an app exists, the setup page only offers the login. To connect a different app, you would have to reinstall the instance.
::

## Inviting Your Team

Only GitHub accounts on the member list can sign in. Everyone else sees "Access denied" after the GitHub login. The list is under Settings > Access. Enter a GitHub login and click "Invite". The account can sign in right away, its name and avatar show up after the first login.

![The Access page under Settings, with the current members and an invite field for a new GitHub username](https://knecht.works/assets/knecht-settings-user.png)

Every member has the same access as the owner, including inviting and removing members. The owner is the account that created the GitHub App and is the only member that cannot be removed.

## Connecting Integrations

The AI provider is required for the AI action and lives under Settings, Agent. Issue trackers are optional and live under Settings, Integrations.

### AI Provider

The AI action runs an agent inside the run's environment, authenticated against one provider with one key. Under Settings > Agent, pick the provider, paste the key, and choose a default model. The key is stored encrypted and is not shown again. Supported providers:

- OpenCode Zen and OpenCode Go, two separate plans. Both take a service account key (`oc_sk_…`) from the [OpenCode console](https://opencode.ai/console){rel="&#x22;nofollow&#x22;"}. Pick the plan you pay for, the model lists differ.
- Anthropic, OpenAI, and Google with their own API keys.
- Langdock, a gateway with an EU or US region. The region applies to every request of the instance.

The model list comes from the selected provider. For OpenCode it comes from your workspace, so models disabled there do not show up. The optional subtask model is used when the agent delegates smaller tasks. Each AI step in a workflow can override the default model. The instructions field on the same page is covered on [AI Agent](https://knecht.works/docs/usage/agent).

![The Agent page under Settings, with the provider, API key, and default and subtask model fields](https://knecht.works/assets/knecht-settings-ai.png)

::tip
Beta testers get OpenCode credit from us. How to get the key and where to paste it is on [Beta Testers](https://knecht.works/docs/resources/beta-testers#getting-your-opencode-credit).
::

If the installation preset the key, for example through `KNECHT_AI_KEY`, the field is locked in the dashboard and shows "Preset by the installation".

### Issue Trackers (Optional)

Issues in a connected issue tracker can start workflows, the agent answers on them, and finished runs comment the pull request link back on them. Each connection needs an API token, a webhook registered in the tool, and a link between each project and its counterpart there. Which tools are supported is listed under [Trigger Types](https://knecht.works/docs/usage/triggers#trigger-types), and the Setup section of each tool's page walks through all of it.


# Maintenance

A self-hosted instance needs three things from its operator: updates, a backup, and an eye on certificates. All of it happens on the server, on the System page of the dashboard, or under Settings, Advanced. Managed beta instances are maintained by us, so this page only applies to self-hosted installs.

## Updating

Releases are git tags in the form `vX.Y.Z`, built by CI into a Docker image. When a newer release exists, the System page shows its release notes and an update button. Automatic updates are set under Settings, Advanced.

### Manual Updates

The System page shows an "Update to vX.Y.Z" button. It swaps the app to the new version with all data intact and takes about a minute, during which the dashboard is unreachable. Only the owner can start it, because it changes the running code for every member.

::note
The manual equivalent on the server, for example when the dashboard is down:

```bash
cd /opt/knecht
git fetch --tags && git checkout vX.Y.Z
sed -i 's/^KNECHT_VERSION=.*/KNECHT_VERSION=vX.Y.Z/' .env
docker compose pull && docker compose up -d
```
::

### Automatic Updates

Under Settings, Advanced, the panel "Automatic updates" has a field for a cron expression in server time, for example `0 3 * * *` for nightly at 03:00. Once set, Knecht updates itself as soon as a new release exists and no run is active. Leave the field empty to update by hand.

### Host-Level Updates

The in-app update covers the app only. Docker, the [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} CLI, and the DDEV image warm-up live on the host and are not touched. When a release needs a newer DDEV or a changed host setup, the release notes say so, and the provisioning script has to be re-run once:

```bash
sudo KNECHT_UID=1000 KNECHT_GID=1000 /opt/knecht/scripts/provision-host.sh
```

The script is idempotent and safe to run at any time.

### Pre-Releases

Tags with a hyphen, such as `v0.3.0-rc.1`, are pre-releases. CI builds them like any release, but they are never offered as an update and a normal install ignores them. To test one, fetch the installer from that tag and pin the same tag with `KNECHT_REF`, so installer and version cannot diverge:

```bash
curl -fsSL https://raw.githubusercontent.com/knecht-works/knecht-cloud/v0.3.0-rc.1/scripts/install.sh \
  | sudo env KNECHT_DOMAIN=knecht.example.com KNECHT_REF=v0.3.0-rc.1 bash
```

Once the matching stable release is published, the instance offers it as a regular update. Updating from a stable version to a pre-release is not possible.

## Backup and Rollback

All state lives in `/data/knecht/data`: the SQLite database, run archives, and uploaded database dumps. Back that folder up, or snapshot the whole server. Project checkouts under `/data/knecht/projects` are disposable, Knecht clones them again when needed.

::warning
Stored secrets, such as the GitHub App credentials, the AI key, and the tokens of connected integrations, are encrypted with a key derived from `NUXT_SESSION_PASSWORD` in `/opt/knecht/.env`. A backup of the data folder alone cannot be restored without that file. Keep a copy of the `.env` as well, ideally separate from the data backup.
::

Database migrations run forward only. Checking out an older release does not roll the schema back. Take a copy of `/data/knecht/data` before an update if you want a safe way back, and restore the copy together with the older tag.

On a Mac, both folders live inside the Lima VM. Reach them through `limactl shell knecht`, or back up the VM disk as a whole.

## Certificates

Caddy handles TLS on its own. It fetches the certificate for the dashboard on first start and one certificate per preview hostname on demand, so the first visit of a new preview URL takes a few extra seconds. Nothing needs renewing by hand.

Let's Encrypt issues at most 50 new certificates per week per domain. Each newly visited preview hostname uses one, renewals do not. A team with many sessions per week can hit that limit. The way out is a wildcard certificate for the preview zone:

1. Delegate the preview subzone to a DNS provider with an API, for example `preview.knecht.example.com NS -> Hetzner DNS`. The main zone stays where it is.
2. Build Caddy with the matching DNS plugin.
3. In `/opt/knecht/Caddyfile`, replace `on_demand` with `tls { dns <provider> }`.


# Projects

A project is a GitHub repository connected to Knecht, together with what it needs to boot: environment variables, a database dump, and a few settings. This page covers what kind of projects work, how to add one, and what you can do with it afterward.

## Supported Stacks

Knecht boots projects with [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"}. These are tested on real projects and run in our test suite:

::docs-stack-grid
  :::docs-stack-item{icon="i-simple-icons-craftcms" to="https://craftcms.com"}
  Craft CMS
  :::

  :::docs-stack-item{icon="i-simple-icons-drupal" to="https://www.drupal.org"}
  Drupal 10 and 11
  :::

  :::docs-stack-item{icon="i-simple-icons-kirby" to="https://getkirby.com"}
  Kirby
  :::

  :::docs-stack-item{icon="i-simple-icons-laravel" to="https://laravel.com"}
  Laravel
  :::

  :::docs-stack-item{icon="i-simple-icons-typo3" to="https://typo3.org"}
  TYPO3
  :::

  :::docs-stack-item{icon="i-simple-icons-php" to="https://www.php.net"}
  Plain PHP with Vite
  :::
::

Any other repository is expected to work too. A `.ddev/config.yaml` boots from that file as it is, with the framework, PHP version, and database read straight from it.

Without one, Knecht generates an environment from:

- The PHP version from `composer.json`.
- The Node version from `.nvmrc`, `engines.node`, a mise config, or `.tool-versions`.
- The package manager from the lockfile.

::note
If a project outside the tested list misbehaves, that is a bug worth reporting. One known difference to local DDEV concerns Vite dev servers, which in some setups need one line of config. The cases are collected on [Troubleshooting](https://knecht.works/docs/resources/troubleshooting).
::

## Adding a Project

"New project" on the projects page opens a short guided setup. The project exists after the first step, everything after that is optional and can be changed later in the project settings.

::steps{level="3"}
### Connect the Repository

Pick a repository from those the GitHub App is installed on, and a branch. It defaults to the repository's default branch. Runs check out this branch and open pull requests against it. The branch is fixed per project, another branch can be chosen per run.

### Set Environment Variables

Paste the project's `.env`, one `KEY=value` per line, or skip and add them later.

  :::tip
  Values can use `$KNECHT_PREVIEW_URL` and `$KNECHT_DEV_SERVER_URL`. Knecht fills them per run, so a variable such as `APP_URL=$KNECHT_PREVIEW_URL` always points at the current preview.
  :::

### Import a Database

Upload a dump as `.sql`, `.gz`, `.zip`, `.bz2`, `.xz`, `.tar`, or `.mysql`. It is imported into the environment on the first boot and stays there for later runs. Without a dump, the project boots with an empty database.

### Boot and Preview

The last step offers "Open project" and, as long as the bundled `boot-and-preview` workflow exists, "Boot & preview". Boot runs that workflow right away: it imports the database, builds the project, and opens a preview so you can confirm the project comes up. Open project skips that and shows the project page, where the same can be started later.
::

## Working with a Project

Everything from the guided setup lives in the project settings and can be changed there. "Settings" in the top right of the project page opens them. Beyond the setup values, the settings hold the Mentions panel with the starter workflow, a link panel for each connected issue tracker, and "Persistent folders" for files that should survive across runs.

![The project settings page, with panels for env variables, agent instructions, environment, boot commands, dev server, and database dump](https://knecht.works/assets/knecht-project-settings.png)


# Workflows

A workflow is a list of steps Knecht runs on a project, one after the other, inside the project's own environment. Each step executes one action. A workflow is built once and can then be started by hand or by a trigger on any number of projects.

## Building a Workflow

The workflow editor shows the steps as a numbered rail. Steps are added from the library, reordered by drag and drop, and configured in place. Every edit is saved automatically. Steps run in order, there are no parallel branches.

![The workflow editor for a Summarize PR workflow, with Run in the header, a GitHub pull request trigger with its events, conditions, and projects, a Boot project and an AI step, and the step library on the right](https://knecht.works/assets/knecht-workflow-ki-summarize.png)

### Run Variables

Steps reference earlier results and trigger data with double curly braces. Typing `{{` in any field opens an autocomplete with what is available at that point. The namespaces:

| Run variable                          | Holds                                                                                                                                                                               |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `{{ steps.<id>.<output> }}`           | An output of an earlier step, for example `{{ steps.update.stdout }}`. The id is derived from the step's label and editable.                                                        |
| `{{ inputs.<field> }}`                | What the trigger delivered: `title`, `body`, `url`, `identifier` (the issue or pull request number, or the ticket key), plus `event`, `status`, `labels`, `assignee`, and `author`. |
| `{{ run.id }}` and `{{ run.url }}`    | The run's number and its page in the dashboard.                                                                                                                                     |
| `{{ project.name }}`                  | The project's name, also `owner`, `fullName`, and `defaultBranch`.                                                                                                                  |
| `{{ preview.url }}`                   | The preview URL after the boot step. The boot step also delivers it as its output `{{ steps.<id>.url }}`, which is the form the autocomplete offers.                                |
| `{{ loop.item }}`, `{{ loop.index }}` | Inside a Loop step, the current item and its index, starting at 0.                                                                                                                  |

A missing value renders as an empty string, so a run variable for something a step has not produced yet does not break the run.

## Triggers

Triggers sit at the head of the workflow in the editor and define when it starts on its own. Knecht offers GitHub events, issue trackers, and cron schedules. Starting a workflow by hand needs no trigger. "Pause triggers" in the menu of the editor header turns all triggers of a workflow off, and a paused workflow says so above its triggers. Each trigger, its options, and the inputs it delivers are described on [Triggers](https://knecht.works/docs/usage/triggers). The steps and agent commands that write back are described on the page of each integration.

## Testing before You Activate

"Run" in the editor header starts the workflow on a project and branch of your choice, with the current draft. The test runs under the same rules as a real run, in the project's environment, with the log streaming into the editor. A collapsed section in the run popover lets you type a mock trigger event, so run variables such as `{{ inputs.title }}` can be tried without a real issue. The editor remembers the last mock inputs per workflow in your browser.

A draft that is not complete cannot run. The header lists what is missing, and clicking an entry opens the affected step.

## Reporting Back

When a run in the session of an issue tracker issue finishes, Knecht comments on that issue without any step in the workflow:

- **A pull request was opened.** "Knecht opened a pull request for this issue" with the link. The tool's own word stands in for "issue", for example "ticket" in Jira.
- **The run failed.** "Knecht could not finish the run for this issue" with the link to the run in the dashboard.
- **Succeeded without a pull request.** Nothing. Whatever the agent replied stands on its own.

Runs on a GitHub issue or pull request get no such comment.

## Workflows as Code

The overflow menu in the editor exports a workflow as YAML or JSON. "Import" on the workflows page creates a workflow from such a file. The export format is a plain step list, so a workflow can live in a git repository, be reviewed like code, and be moved between instances. Hand-written files are accepted as well and can use the short form:

::docs-workflow-yaml{filename="demo-pr.yaml"}
```yaml
version: 1
name: demo-pr
description: Make a small change and open a PR.
steps:
  - create-branch:
      name: knecht/demo-{{ run.id }}
  - bash:
      command: date > .knecht-demo.txt
  - create-commit:
      message: "Knecht demo change (run {{ run.id }})"
  - create-pr:
      title: "Knecht demo (run {{ run.id }})"
      description: |
        Automated demo change by Knecht, run {{ run.id }} on {{ project.name }}.
```
::


# Triggers

A trigger starts a workflow without anyone pressing "Run". It sits at the head of the workflow in the editor, targets one or more projects, and starts a run each time it fires. A workflow can have any number of triggers, also several of the same kind. Starting a workflow by hand needs no trigger, see [Testing before You Activate](https://knecht.works/docs/usage/workflows#testing-before-you-activate).

## Trigger Types

| Type     | Starts a run when                                                                                               | Details                                                          |
| -------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| Schedule | A cron expression is due, for example every Monday at 09:00.                                                    | [Schedule](https://knecht.works/#schedule) below                 |
| GitHub   | Something happens on a pull request or an issue: opened, ready for review, new commits, a label, an assignment. | [GitHub](https://knecht.works/docs/integrations/github#triggers) |
| Jira     | Something happens on a ticket: created, assigned to Knecht, a label, a status.                                  | [Jira](https://knecht.works/docs/integrations/jira#triggers)     |
| Plane    | Something happens on a work item: created, assigned to Knecht, a label, a state.                                | [Plane](https://knecht.works/docs/integrations/plane#triggers)   |
| Linear   | Something happens on an issue: created, assigned to Knecht, a label, a status.                                  | [Linear](https://knecht.works/docs/integrations/linear#triggers) |

This table is the list of sources. Each one has its own page with its events, conditions, and setup, and everything on this page applies to all of them.

GitHub works on every instance. An issue tracker has to be connected first, the Setup section of its page walks through it. Until then, the dialog shows a hint with the way to Settings, Integrations instead of the form. All sources except the schedule arrive through webhooks, so they need an instance that is reachable from the internet.

## Adding a Trigger

"Add trigger" below the triggers of a workflow opens the dialog. Pick the source, one or more projects, and what the source should react to. For an issue tracker, only projects that are linked to their counterpart in the tool are listed. The link is set in the project settings.

![The trigger dialog with Linear selected as source, one linked project, the event Created ticked, and the condition Status is Any Triage](https://knecht.works/assets/knecht-trigger-linear.png)

Once saved, the trigger appears as a row at the head of the workflow. The row names the source and reads like a sentence, for example "on opened, ready for review, pushed" and below it "if base branch `main` and author not `renovate[bot]`". The projects stand as chips on the right. A click on the row opens the dialog again. The switch on the row pauses that one trigger, the menu next to it deletes it.

### Events and Conditions

All triggers except the schedule share one form with two sections.

- **Fires when any of these happens.** The events. Any ticked event fires the trigger. Some take values, such as the labels of "Label added". An event with several values fires on any of them.
- **But only if.** The conditions. Each one names a field, "is" or "is not", and one or more values. "is" holds when the object has one of the values, "is not" when it has none of them.

"Add condition" starts the first group. "and" adds a condition to a group, and every condition of a group has to hold. "or group" adds another group, and the trigger fires when one of the groups holds. A pull request trigger with the events "Opened" and "Label added", one group "base branch is `main` and author is not `renovate[bot]`", and a second group "label is `urgent`" fires on either event for pull requests against `main` that the bot did not open, and for every pull request labeled `urgent`. Which events and fields a source has is listed on its page, see [Trigger Types](https://knecht.works/#trigger-types).

### Matching

The values of events and conditions follow the same rules in every source.

- **Picked from the tool.** Labels, statuses, issue types, priorities, and the draft state of a pull request are picked from a list, read live from the tool. They are compared exactly, and a value that is not in the list cannot be typed.
- **Patterns.** Branches and GitHub logins are typed, with the branches and assignees of the repository as suggestions. A condition on them takes a pattern: `*` stands for any text, so `releases/*` matches `releases/v1` and `*[bot]` every bot account. Without a `*` the value has to match as a whole. The login of the event "Assigned to" is no pattern and is matched exactly.
- **Upper and lower case count.** `Bug` does not match `bug`. This holds for every value, logins included.

With several projects selected, labels and statuses that exist in only some of them are listed under "Only in some", with the keys of their counterparts in the tool. If a picked value of an event is missing in one of the projects, the form warns that nothing there will ever fire the trigger. Pick a value all projects share, or create a second trigger.

### Issue Trackers

Issue trackers share the events "Created", "Assigned to Knecht", "Label added", and an event for a status being reached. An issue that is created with the label or already assigned to Knecht fires as well, without "Created" being ticked. An issue that is created in a status does not reach it, the status event only fires on a move.

The status list has two groups.

- **Category.** An entry such as "Any Done" stands for a whole status category of the tool, whatever the single statuses are called. The event fires when an issue crosses into the category. A move inside it, for example from "In Progress" to "In Review", does not fire.
- **Exact status.** The statuses of the selected projects, read live from the tool. The event fires every time an issue moves into that status.

The same list serves the condition "Status", which checks the status the issue is in right now. "Created" with the condition "Status is Any Triage" fires for new issues that land in triage, "Status is not Any Done" keeps closed issues out. The condition "Assignee is Knecht" holds while the issue is assigned to the account behind the connection.

#### Knecht Holds the Issue

While a run or a mention works on an issue, the issue is assigned to the Knecht account, like a colleague who picks it up. Once the session has no more work to do, Knecht hands it back: to the person whose change started the run, else to whoever held the issue before Knecht, else to whoever created it. A cancelled run hands back as well. If somebody took the issue from Knecht in the meantime, it stays with them.

Knecht taking the issue itself does not fire "Assigned to Knecht". Labels and statuses the agent sets fire triggers as usual, and the condition "Assignee is Knecht" holds while Knecht works on the issue. Plane, where a work item takes several assignees, differs a little, see [Plane](https://knecht.works/docs/integrations/plane#knecht-holds-the-work-item).

## How Triggers Behave

- **Pausing.** "Pause triggers" in the menu of the editor header turns all triggers of a workflow off. A paused workflow shows "Paused: triggers won't fire" above its triggers, with a switch that turns them on again. Each trigger also has its own switch. Manual runs are not affected by either.
- **Last complete version.** Triggers run the last version of the workflow that passed validation. An incomplete edit stays a draft and the previous complete version keeps running.
- **One run per project.** A schedule starts one run for every project of the trigger. Every other event only runs on the project whose repository or linked counterpart in the issue tracker sent it.
- **One run per change.** An issue or pull request that is created or edited with several changes at once, for example opened with a label and an assignee, starts one run, not one per change.
- **Sessions.** Runs on a GitHub issue or pull request or on an issue of an issue tracker join its [session](https://knecht.works/docs/get-started/concepts#sessions), so two triggers firing on the same issue run one after the other. Scheduled and manual runs get a session of their own that closes after the run.
- **Inputs.** All triggers except the schedule fill the run variables `{{ inputs.identifier }}`, `{{ inputs.title }}`, `{{ inputs.body }}`, `{{ inputs.url }}`, `{{ inputs.event }}`, `{{ inputs.status }}`, `{{ inputs.labels }}`, `{{ inputs.assignee }}`, and `{{ inputs.author }}`. A field the event does not have arrives as an empty string. A schedule delivers no inputs.

## Schedule

A schedule fires on a standard five-field cron expression: minute, hour, day of month, month, day of week. The form offers presets from every 15 minutes to weekly on Monday at 09:00.

![The trigger dialog with Schedule selected as source, three projects as chips, the cron expression for daily at 09:00, and the presets below the field](https://knecht.works/assets/knecht-trigger-schedule.png)

Times are in the server's local time. Supported are `*`, steps like `*/15`, ranges like `1-5`, and lists like `1,15`. Seconds and aliases like `@daily` are not supported. [crontab.guru](https://crontab.guru){rel="&#x22;nofollow&#x22;"} explains the format and translates an expression into plain words. If the instance was down when a slot passed, the schedule fires once after the restart, not once per missed slot.


# AI Agent

The AI step starts [opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"} inside the project's environment with your provider key. It is an agent, not a chat: it reads the code, changes files, runs commands, and checks its own work until the task in the prompt is done. This page covers where it runs, how to steer it, and what it hands back to the workflow.

## Where It Runs

The agent runs inside the web container of the booted project, as a non-root user, on the run's checkout. Composer, npm, and git are there, so it behaves like a developer on the real project. What it cannot reach:

- **Docker and the host.** The Docker socket and the [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} CLI stay on the Knecht side. The agent only ever sees the inside of its container.
- **Other runs.** Each environment sits on its own network, parallel runs cannot reach each other.
- **Secrets.** The provider key is handed to the process as an environment variable and never written into the checkout. Git pushes go through a short-lived token scoped to the session's one repository.

A small set of Knecht commands is available to the agent inside the container: git with credentials for the project's repository, a command to push the branch and open a pull request, and, when the session belongs to a GitHub issue or pull request or to an issue of an issue tracker, commands to read the thread, post a reply, add or remove existing labels, and, in an issue tracker, move it to another status. What each of them does is on the page of the integration, in the section about the agent, for example on [GitHub](https://knecht.works/docs/integrations/github#the-agent-on-issues-and-pull-requests).

## Instructions

Three layers of instructions apply, in this order:

1. **Built-in rules.** Knecht ships its own rules for working style, git usage, memory, and how to reply on a thread. They are the same on every instance.
2. **Instance instructions.** Settings > Agent has a free text field that applies to every project, for example "Always answer in German" or "Never touch anything under legacy/".
3. **Project instructions.** The project settings have the same field for rules that apply to this project only, for example where the styles live or which design tokens to use.

On top of that, an AI step can carry its own step prompt, a task framing for that one step. A repository's own `AGENTS.md` is read by opencode as usual.

## Memory

The agent keeps notes per project, so it does not rediscover the same facts on every run: how the project builds, where the styles live, corrections from earlier follow-ups. The notes live on the host outside every environment and are copied into the checkout before each agent call and back afterwards.

The structure is an index file, `MEMORY.md`, that is part of the agent's instructions on every call, plus topic files the agent reads on demand. The agent writes and curates the notes itself, guided by the built-in rules. The index is capped at 2 KB and the whole store at 64 KB. An oversized write is discarded and the previous state kept.

::note
There is no view of the notes in the dashboard yet.
::

## Output Fields

By default, an AI step returns the agent's final text under `{{ steps.<id>.text }}`. For later steps that need specific values, the step's "Output format" field declares them, one per line:

```text
prTitle: string
labels: string[]
needsReview: boolean
```

The allowed types are `string`, `number`, `boolean`, and their array forms. The agent writes the result as a file, Knecht validates it against the declaration and asks the agent to fix it if it does not match. Each field is then available as `{{ steps.<id>.json.<field> }}`, for example as the title of the pull request step.

## Models

The default model and an optional subtask model are set under Settings > Agent. The subtask model is used when the agent delegates smaller pieces of work, for example exploring the repository. Each AI step has a model field that overrides the default, so one workflow can mix a small model for triage and a large one for the fix, all behind the same key.

Switching the provider clears both stored models, because model names do not carry over between providers. Pick them again after the switch.

## Follow-Ups and Mentions

The conversation does not end with the run. Every session has one agent conversation, and every run and follow-up in that session continues it, so later work sees what earlier work found. Two ways to continue:

- The follow-up chat on the run page sends a new prompt into the session's environment.
- A mention in a comment does the same from GitHub or an issue tracker, see [Mentions](https://knecht.works/#mentions) below.

![The follow-up panel on the run page, with a request to add a dark mode, the agent's reply with its collapsed tool calls, and the input field for the next message with the model picker](https://knecht.works/assets/knecht-run-follow-up.png)

Follow-ups in one session run one after the other. A stopped environment is restarted for the follow-up, an archived one is restored first.

::note
For a walkthrough of setting this up end to end, see [Exploring Knecht Cloud: Talking to an AI Agent in GitHub Issues](https://matthias-andrasch.eu/blog/2026/exploring-knecht-cloud-talking-to-an-ai-agent-in-github-issues-part-2/){rel=""nofollow""}.
::

### Mentions

A mention is a comment that addresses Knecht. Knecht runs the text of the comment as a follow-up and posts the answer as a comment in the same thread.

**Set it up once per project.**

1. Open the project settings and go to the Mentions panel.
2. Pick a "Starter workflow" and make sure it is published. It boots the environment when a mention arrives on an issue Knecht has not worked on yet, so a workflow with a boot step is the right choice.

**Mention Knecht.**

| Where                        | Write                                                                                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GitHub issue or pull request | `@knecht-works fix the broken footer link`                                                                                                               |
| Issue tracker                | Mention the account Knecht is connected with, the way you mention a colleague, followed by the instruction. `@knecht` typed as plain text works as well. |

The issue has to belong to a project in Knecht: its repository on GitHub, or the project linked to it in an issue tracker.

**What happens.**

1. Knecht looks up the session of the issue. If there is none, or its environment is down, the starter workflow runs first.
2. The comment runs as a follow-up in that environment, with the agent conversation of the session.
3. The answer arrives as a comment. If a pull request was opened, its link is part of it.

**If nothing happens.**

| Knecht answers    | Reason                                                                                                                                                                                                                                  |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| With a setup hint | No starter workflow is chosen, or it is not published.                                                                                                                                                                                  |
| Not at all        | "Answer mentions in this repo" is off in the Mentions panel under Advanced, the issue belongs to no project, or the comment comes from an account that may not mention Knecht, on GitHub one that is not listed under Settings, Access. |

Who may mention Knecht depends on the tool: on GitHub only the accounts that can sign in to your Knecht dashboard (Settings, Access), in an issue tracker everyone who can comment on the issue. Comments by Knecht itself are always ignored. The Mentions section on the page of each integration has the details.


# GitHub

GitHub is the integration every instance has. The GitHub App created during setup signs your team in, lists the repositories that become projects, delivers the events that start workflows, and lets the agent push branches, open pull requests, and answer on issues. This page collects what that covers and how to use it in workflows.

## Setup

The GitHub App is created once, on the setup page of a fresh instance. [Setup](https://knecht.works/docs/get-started/setup#creating-the-github-app) walks through that flow. Once the app is installed on a repository, that repository is ready. There is nothing to configure per repository, no webhook and no token.

What the app is allowed to do on the repositories it is installed on:

| Access               | Used for                                                                                                 |
| -------------------- | -------------------------------------------------------------------------------------------------------- |
| Contents, write      | Checking out the code and pushing branches                                                               |
| Pull requests, write | Opening pull requests                                                                                    |
| Issues, write        | Reading issues, posting comments, and setting labels. Comments on pull requests go through the same API. |
| Metadata, read       | Listing repositories and branches                                                                        |

It subscribes to three webhook events: pull request, issues, and issue comment. Everything on this page is built from those.

## Capabilities

### Triggers

A GitHub trigger watches the repositories of the selected projects and starts one run for the project whose repository sent the event. The tabs "Pull request" and "Issue" at the top of the form decide what the trigger is about. Below them, "Fires when any of these happens" lists the events and "But only if" the conditions. Any ticked event fires the trigger, and one group of conditions has to hold. How the two sections work in general is on [Triggers](https://knecht.works/docs/usage/triggers#events-and-conditions).

![The trigger dialog with GitHub selected as source, two projects as chips, the Pull request tab, the events Opened, Ready for review, and New commits pushed ticked, the condition Base branch is main, and an or group with Label is bug](https://knecht.works/assets/knecht-trigger-github.png)

#### Pull Request Events

| Event              | Fires when                                                                                                      |
| ------------------ | --------------------------------------------------------------------------------------------------------------- |
| Opened             | A pull request is opened or reopened. Ticked by default.                                                        |
| Ready for review   | A draft is marked as ready for review.                                                                          |
| New commits pushed | Commits are pushed to the pull request, force pushes included. Every push starts a run.                         |
| Label added        | One of the picked labels is added to the pull request. The labels are picked from the labels of the repository. |

Runs check out the pull request's branch.

#### Pull Request Conditions

| Field       | Compares against                                                                   |
| ----------- | ---------------------------------------------------------------------------------- |
| Base branch | The branch the pull request targets, for example `main` or `releases/*`.           |
| Head branch | The pull request's own branch, for example `renovate/*` for every Renovate branch. |
| Author      | The login that opened the pull request.                                            |
| Assignee    | The logins the pull request is assigned to.                                        |
| Label       | The labels on the pull request.                                                    |
| PR state    | "Draft" or "Ready for review".                                                     |

Each condition takes "is" or "is not". Branches and logins are typed, with the branches and assignees of the repository as suggestions, and take patterns. Bots are written the way GitHub shows them, for example `renovate[bot]`. Labels and the PR state are picked from a list. Upper and lower case count, in logins too. The rules are the same for every source, see [Matching](https://knecht.works/docs/usage/triggers#matching).

::tip
A pull request that is opened as a draft never passes "PR state is Ready for review" with the Opened event alone. Tick "Ready for review" as well, and the run starts the moment the draft is released.
::

#### Issue Events and Conditions

![The trigger dialog on the Issue tab, with the events Opened and Label added with the labels bug and enhancement ticked, and the condition Author is not \*bot](https://knecht.works/assets/knecht-trigger-github-issue.png)

| Event       | Fires when                                                                                                                                                                                        |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Opened      | A new issue is opened, or a closed one is reopened. Ticked by default.                                                                                                                            |
| Label added | One of the picked labels is added to the issue. The labels are picked from the labels of the repository.                                                                                          |
| Assigned to | The issue is assigned to one of the named GitHub logins. The assignees of the repository are suggested, other logins can be typed. The login has to match exactly, upper and lower case included. |

Issues take the conditions "Author", "Assignee", and "Label", with the same rules as on pull requests. Runs check out the project's default branch.

#### Inputs

Both kinds fill the same run inputs: `identifier` is the number, plus `title`, `body`, `url`, `status`, `labels`, `assignee`, and `author`. `event` is `pull_request` or `issues`. Pausing, versioning, and the shared behavior of all triggers are on [Triggers](https://knecht.works/docs/usage/triggers).

### Sessions on Issues and Pull Requests

A run started by an issue or pull request joins the [session](https://knecht.works/docs/get-started/concepts#sessions) of that issue or pull request. The session keeps the checkout, the environment, and one agent conversation, so a later trigger or a mention continues where the last run stopped. Closing the issue closes the session, reopening it revives the session. Scheduled and manual runs have no issue behind them and get a session of their own that closes after the run.

### Workflow Steps

Three steps in the Output group of the step library work with GitHub. They run in any workflow, no matter whether a GitHub event, a schedule, or a click started it.

| Step          | Fields                                                                                                                                                      | Outputs                                              |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| Create branch | Branch name, for example `knecht/{{ run.id }}`. Branches off the current checkout.                                                                          | `{{ steps.<id>.name }}`                              |
| Create commit | Commit message. Commits everything the run changed under the app's bot account. Nothing to commit is skipped, not an error.                                 | `{{ steps.<id>.sha }}`, empty when nothing changed   |
| Pull request  | Title and Description. Pushes the branch and opens a pull request against the project's default branch. Needs a Create branch step earlier in the workflow. | `{{ steps.<id>.url }}` and `{{ steps.<id>.number }}` |

Knecht appends a link to the preview environment to every pull request description. A branch without commits is skipped without failing, and the step then produces no outputs. The run page shows an "Open Pull Request" button once a pull request exists.

### The Agent on Issues and Pull Requests

When the run's session belongs to an issue or pull request, the [agent](https://knecht.works/docs/usage/agent) gets four commands inside the environment. The prompt of an AI step only has to name what to do with them.

- **Read the thread.** Title, state, author, assignees, labels, body, and the last ten comments, so a follow-up sees what was said in the meantime.
- **Reply.** Posts a comment on the issue or pull request. Knecht appends the preview link and, when one exists, the pull request link.
- **Set labels.** Adds or removes labels of the repository. Knecht never creates labels, so the ones the agent should use have to exist before the run.
- **Open a pull request.** Pushes the current branch and opens a pull request against the default branch, without the git steps above. The agent refuses to do this on the default branch itself.

### Mentions

Comment on an issue or pull request of the project's repository:

```text
@knecht-works fix the broken footer link
```

The name of your GitHub App works instead of `@knecht-works` as well. Knecht reacts with an eyes emoji, runs the comment as a follow-up, and posts the answer in the thread.

Knecht only answers GitHub accounts that can sign in to your Knecht dashboard: the owner and everyone invited under Settings, Access, see [Inviting Your Team](https://knecht.works/docs/get-started/setup#inviting-your-team). Write access to the repository is not enough. Comments from all other accounts and from bots are ignored.

The one-time setup, what happens step by step, and what to check when Knecht stays silent is on [Mentions](https://knecht.works/docs/usage/agent#mentions).

## Examples

The workflows below can be built in the editor or imported from YAML under Workflows, "Import". Triggers are added in the editor after the import.

### Software Factory

Three workflows that hand an issue from one to the next. The triage checks every new issue and sets the label `bug` or `enhancement`, and that label fires the trigger of the matching workflow. A bug comes back with a pull request, an enhancement with a plan that a mention in the thread turns into a pull request.

All of it runs in the [session](https://knecht.works/#sessions-on-issues-and-pull-requests) of the issue. The triage boots the site once and every later run finds it running, so only the triage has a boot step. The prompts do not repeat title or body, because the agent reads the issue of its session itself. Both labels have to exist in the repository, `bug` and `enhancement` are GitHub's defaults.

#### Triage

| Source        | Fires When | But Only If   |
| ------------- | ---------- | ------------- |
| GitHub, Issue | Opened     | No conditions |

::docs-workflow-yaml{filename="github-issue-triage.yaml"}
```yaml
version: 1
name: GitHub Issue Triage
description: Check every new issue and label it as bug or enhancement.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: 'Read the issue of this session. Try to reproduce it on the preview and
      in the code. Do not fix anything. Then apply exactly one label: "bug" if
      something is broken, "enhancement" if it was never built. If the report
      lacks the details to decide, apply no label and ask the reporter in the
      thread.'
    id: triage
    label: Triage
```
::

#### Bug Fix

| Source        | Fires When         | But Only If   |
| ------------- | ------------------ | ------------- |
| GitHub, Issue | Label added: `bug` | No conditions |

::docs-workflow-yaml{filename="github-bug-fix.yaml"}
```yaml
version: 1
name: GitHub Bug Fix
description: Fix an issue labeled as bug and open a pull request.
steps:
  - type: ai
    prompt: The issue of this session was confirmed as a bug. Fix it on a work
      branch, verify the fix on the preview, commit, and open a pull request
      that closes the issue. Answer in the thread with a short summary of the
      change.
    id: fix
    label: Bug Fix
```
::

#### Add Enhancement

| Source        | Fires When                 | But Only If   |
| ------------- | -------------------------- | ------------- |
| GitHub, Issue | Label added: `enhancement` | No conditions |

::docs-workflow-yaml{filename="github-add-enhancement.yaml"}
```yaml
version: 1
name: GitHub Add Enhancement
description: Plan an issue labeled as enhancement and post the plan.
steps:
  - type: ai
    prompt: "The issue of this session is an enhancement. Work out how it would be
      built in this project: the files to touch, the steps in order, and what is
      open. Do not change any files. Post the plan in the thread, written for
      the person who opened the issue."
    id: plan
    label: Plan Enhancement
```
::

::note
A label that a person adds to an issue the triage never saw starts these workflows without a booted site. Add a boot step to them if that happens in your team.
::

#### Result

Someone reports that the site has no dark mode. A minute later the triage has labeled the issue as an enhancement.

![A new issue on GitHub that Knecht labeled as enhancement a minute after it was opened](https://knecht.works/assets/issue-creation-with-label.png)

The label starts "GitHub Add Enhancement", and the plan lands in the thread, with the preview link Knecht appends.

![Knecht confirmed the issue as a feature request, added the enhancement label, and posted a plan with a preview link](https://knecht.works/assets/issue-follow-up.png)

A team member agrees and mentions Knecht. It continues in the same session and answers with the pull request.

![The reporter asked Knecht to implement the plan and open a pull request, and Knecht answered with the pull request link and a summary](https://knecht.works/assets/issue-enhancement-finished.png)

### Pull Request Review

Knecht tests every pull request on the running site. The run checks out the pull request's branch and the agent posts its findings as a comment. New commits fire the trigger again in the same session, so the second review knows the first. Do not exclude authors with `*[bot]` if Knecht's own pull requests should be reviewed: they are opened under the app's bot account.

| Source               | Fires When                                   | But Only If                                                                                               |
| -------------------- | -------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| GitHub, Pull request | Opened, Ready for review, New commits pushed | Base branch is `main` and PR state is Ready for review and Author is not `renovate[bot], dependabot[bot]` |

::docs-workflow-yaml{filename="github-review-pr.yaml"}
```yaml
version: 1
name: GitHub Pull Request Review
description: Test each pull request on the preview and comment the findings.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: "Review the pull request of this session. Read the diff against {{
      project.defaultBranch }}, then check the change on the preview. Post one
      comment: what the change does, what you tested, and anything that looks
      wrong. Do not change any files."
    id: review
    label: Review Pull Request
```
::


# Jira

The Jira integration connects a Jira Cloud site to your instance. Tickets start workflows, the agent reads and answers on them, moves them through the board, and Knecht reports the finished pull request back on the ticket.

## Setup

You need a Jira Cloud site and an account Knecht acts as. A dedicated account named "Knecht" is worth the extra seat: comments show up under its name, "assign it to Knecht" becomes a normal assignment in Jira, and the account's permissions limit what Knecht can see. Registering the webhook in step three needs Jira administrator rights, once.

::steps{level="3"}
### Create an API Token

Sign in to Atlassian as the account Knecht should use and open [API tokens](https://id.atlassian.com/manage-profile/security/api-tokens){rel=""nofollow""}. "Create API token", give it a name such as "Knecht", and copy the token. It starts with `ATATT` and is shown only once.

### Connect the Account

In your instance, open Settings, Integrations. The Jira panel has three fields:

- **Site URL.** The Atlassian site, for example `https://acme.atlassian.net`. It has to start with `https://`.
- **Email.** The email of the account from step one.
- **API token.** The token from step one.

"Connect" checks the credentials against Jira before anything is stored and shows "Connected as" with the account's name on success. The token is stored encrypted and not shown again. "Reconnect" replaces the token later, "Disconnect" removes the connection.

![The Jira panel under Settings, Integrations, connected to an account, with the site URL, email, and API token fields, and the webhook URL and secret below](https://knecht.works/assets/knecht-integration-settings-jira.png)

### Register the Webhook in Jira

Jira does not call Knecht until you tell it to. After connecting, the panel shows "Waiting for Jira" with the webhook URL and a secret Knecht generated for you, both with copy buttons. "Set up in Jira" opens the webhook page of your site. By hand it is the gear icon, System, and "WebHooks" under Advanced in the sidebar.

  :::warning
  The button that adds a webhook sits at the far right of the WebHooks page and is often outside the visible area. If you only see the search field and the list, scroll the page horizontally all the way to the right.
  :::

Fill in the form:

- **Name.** Anything, for example "Knecht".
- **Status.** Enabled.
- **URL.** The webhook URL from the panel, it ends in `/api/jira/webhook`.
- **Secret.** Paste the secret from the panel. Do not use "Generate secret", Knecht has to know the value, and Jira does not show it again after saving.
- **Issue related events.** In the column Issue tick "created", "updated", and "deleted". In the column Comment tick "created". Everything else stays empty.
- **Exclude body.** Leave it unchecked. Knecht needs the ticket data in the delivery.

![The events section of the Jira webhook form, with created, updated, and deleted ticked under Issue and created ticked under Comment](https://knecht.works/assets/jira-webhook-events.png)

The JQL field above the checkboxes is optional. Left empty, Jira warns that the query matches all issues in all projects. That works, Knecht drops events of projects that are not linked. A query such as `project in (KAN, WEB)` limits the deliveries to the projects you link in the next step. Atlassian describes the form under [Manage webhooks](https://support.atlassian.com/jira-cloud-administration/docs/manage-webhooks/){rel=""nofollow""}.

Save the webhook at the bottom of the form. The summary should list the issue events created, updated, and deleted, the comment event created, and "Exclude body: No".

![The saved webhook in Jira, enabled, with the Knecht URL, the secret set, the issue and comment events, and exclude body set to no](https://knecht.works/assets/jira-webhook-created.png)

### Link a Project to Its Jira Project

Open the settings of a project in Knecht. The Jira panel has one field, "Jira project", listing the projects the account can see. Pick the one whose tickets belong to this repository. One Jira project links to one repository and the other way round. Only linked projects can have Jira triggers.

![The Jira panel in the project settings, with the Jira project field set to a project](https://knecht.works/assets/knecht-project-settings-jira.png)

### Check That Events Arrive

Edit any ticket in the linked Jira project. The status line in the Jira panel under Settings, Integrations switches to "Receiving events" with the last event and ticket key. If it does not:

| Status line says         | What to do                                                                                |
| ------------------------ | ----------------------------------------------------------------------------------------- |
| Wrong secret             | Paste the secret from the panel into the webhook again.                                   |
| Without a body           | Uncheck "Exclude body" in the webhook.                                                    |
| No project is linked     | Link the Jira project in the project settings, see step four.                             |
| Still "Waiting for Jira" | Check that the webhook URL is reachable from the internet and that the events are ticked. |
::

## Capabilities

### Triggers

A Jira trigger watches the Jira projects linked to the selected projects and starts one run for the project whose Jira project the ticket belongs to. The project field only lists projects that are linked. In the form, "Fires when any of these happens" lists the events and "But only if" the conditions. Any ticked event fires the trigger, and one group of conditions has to hold. How the two sections work in general is on [Triggers](https://knecht.works/docs/usage/triggers#events-and-conditions). What all issue trackers share, such as issues that are created with the label already set, is on [Triggers](https://knecht.works/docs/usage/triggers#issue-trackers).

![The trigger dialog with Jira selected as source, two linked projects as chips, the events Assigned to Knecht and Label added with the label knecht ticked, and the conditions Issue type is Bug and Status is not Any Done](https://knecht.works/assets/knecht-trigger-jira.png)

#### Events

| Event              | Fires when                                                           | Notes                                                                                                                                                                                                     |
| ------------------ | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Created            | A new ticket appears in the project.                                 |                                                                                                                                                                                                           |
| Assigned to Knecht | The ticket is assigned to the account behind the connection.         | Ticked by default. Makes "give it to Knecht" a normal assignment in Jira. Knecht taking the ticket itself does not fire, see [Triggers](https://knecht.works/docs/usage/triggers#knecht-holds-the-issue). |
| Label added        | One of the picked labels is added to a ticket.                       | The labels are picked from the labels of the Jira site.                                                                                                                                                   |
| Status reached     | A ticket moves into one of the picked statuses or status categories. | The default is "Any Done". A ticket created in a status does not fire.                                                                                                                                    |

#### Status Reached

The status list has two groups.

- **Category.** "Any To Do", "Any In Progress", and "Any Done" stand for Jira's three status categories, whatever the columns of a board are called.
- **Exact status.** The statuses on the boards of the selected projects.

[Triggers](https://knecht.works/docs/usage/triggers#issue-trackers) explains when a category and when an exact status fires, [Matching](https://knecht.works/docs/usage/triggers#matching) what happens with several projects. If the form warns about a missing status, pick a category, a status all projects share, or create a second trigger.

![The trigger dialog with two projects selected, Status reached set to In Planning, and a warning that this status does not exist in the Jira project KAN](https://knecht.works/assets/knecht-trigger-jira-status-error.png)

#### Conditions

| Field      | Compares against                                                                                   |
| ---------- | -------------------------------------------------------------------------------------------------- |
| Status     | The status the ticket is in, as a category such as "Any Done" or an exact status.                  |
| Assignee   | "Knecht", the account behind the connection.                                                       |
| Issue type | The type of the ticket, for example Bug or Task. The types are read from the linked Jira projects. |
| Label      | The labels on the ticket, read from the Jira site.                                                 |

Each condition takes "is" or "is not". Every value is picked from a list and compared exactly, upper and lower case included. The rules are the same for every source, see [Matching](https://knecht.works/docs/usage/triggers#matching).

#### Inputs

The ticket fills the run inputs: `identifier` is the key such as `PROJ-123`, `title` the summary, `body` the description converted to Markdown, `url` the ticket link, `status` the status name, `labels` the labels, `assignee` and `author` the display names of the assignee and reporter. `event` is `issue`. Pausing, versioning, and shared behavior are on [Triggers](https://knecht.works/docs/usage/triggers).

### Sessions on Tickets

A run started by a ticket joins the [session](https://knecht.works/docs/get-started/concepts#sessions) of that ticket, like a run on a GitHub issue. The session keeps the checkout, the environment, and the agent conversation, so a second trigger on the same ticket or a mention continues the work. The session closes when the ticket reaches a status in the Done category or is deleted, its environment stops once no run needs it any more, and it opens again when the ticket is moved back.

### The Agent on Tickets

When the run's session belongs to a ticket, the [agent](https://knecht.works/docs/usage/agent) gets four commands inside the environment. The prompt of an AI step only has to name what to do with them.

- **Read the ticket.** Type, status, reporter, assignee, labels, the description, and the last ten comments, live from Jira.
- **Reply.** Posts a comment on the ticket. The agent writes Markdown, Knecht converts it to Jira's format and appends the preview link and, when one exists, the pull request link. An `@Name` of the reporter, the assignee, or a commenter becomes a real mention that notifies that person.
- **Set labels.** Adds or removes labels of the Jira site. Knecht never creates labels. If a name does not exist, the agent gets the list of existing labels instead.
- **Move the ticket.** Transitions the ticket to a status by name, for example "In Review". If no transition from the current status leads there, the agent gets the list of reachable statuses instead.

Opening a pull request works through the git steps or the agent's own command, see [GitHub](https://knecht.works/docs/integrations/github#workflow-steps).

### Mentions

Write a comment on a ticket of a linked Jira project, mention the Knecht account the way you mention a colleague, and add the instruction:

```text
@Knecht fix the broken footer link
```

`@knecht` typed as plain text works as well. Knecht runs the comment as a follow-up and posts the answer as a comment.

Whoever can comment on the ticket can mention Knecht, the Jira site is the gate.

The one-time setup, what happens step by step, and what to check when Knecht stays silent is on [Mentions](https://knecht.works/docs/usage/agent#mentions).

## Examples

The workflows below can be built in the editor or imported from YAML under Workflows, "Import". Triggers are added in the editor after the import. All of them assume the project is linked to its Jira project.

### Software Factory

Three workflows that hand a ticket from one to the next. The triage checks every new ticket, sets the label `bug` or `enhancement`, and moves it to "To Do". That move fires the trigger of the workflow whose label condition matches. A bug comes back with a pull request and a ticket in review, an enhancement with a plan that a mention in the comments turns into a pull request.

All of it runs in the [session](https://knecht.works/#sessions-on-tickets) of the ticket. The triage boots the site once and every later run finds it running, so only the triage has a boot step. The prompts do not repeat summary or description, because the agent reads the ticket of its session itself.

::note
Make sure the labels `bug` and `enhancement` exist in Jira first. Jira has no label settings, a label exists once any ticket carries it. Knecht only applies labels that exist, and a trigger only offers labels that exist.
::

#### Triage

| Source | Fires When | But Only If   |
| ------ | ---------- | ------------- |
| Jira   | Created    | No conditions |

::docs-workflow-yaml{filename="jira-issue-triage.yaml"}
```yaml
version: 1
name: Jira Issue Triage
description: Check every new ticket and label it as bug or enhancement.
steps:
  - type: ddev-start
    id: boot_project
  - type: ai
    prompt: >-
      Read the ticket of this session. Try to reproduce it in the preview and in
      the code. Do not fix anything. Then apply exactly one label: "bug" if
      something is broken, "enhancement" if it was never built and then move it
      to "To Do".

      If the ticket lacks the details to decide, apply no label and ask the
      reporter in a comment for clarification. 
    id: triage
    label: Triage
```
::

#### Bug Fix

| Source | Fires When              | But Only If    |
| ------ | ----------------------- | -------------- |
| Jira   | Status reached: `To Do` | Label is `bug` |

::docs-workflow-yaml{filename="jira-bug-fix.yaml"}
```yaml
version: 1
name: Jira Bug Fix
description: Fix a ticket labeled as bug and open a pull request.
steps:
  - type: ai
    prompt: >-
      The ticket of this session was confirmed as a bug. When you are beginning
      your work move the Ticket to "In Progress". Then fix it on a work branch,
      verify the fix on the preview, commit in logical batches, and open a pull
      request. 

      Comment a short summary of the change on the ticket and move it to "In
      Review".
    id: bug_fix
    label: Bug Fix

```
::

#### Add Enhancement

| Source | Fires When              | But Only If            |
| ------ | ----------------------- | ---------------------- |
| Jira   | Status reached: `To Do` | Label is `enhancement` |

::docs-workflow-yaml{filename="jira-add-enhancement.yaml"}
```yaml
version: 1
name: Jira Add Enhancement
description: Plan a ticket labeled as enhancement and post the plan.
steps:
  - type: ai
    prompt: >-
      The ticket of this session is an enhancement. 

      Work out how it would be built in this project: the files to touch, the
      steps in order, and what is open. 

      Do not change any files or the status. Just post the plan as a comment,
      written for the person who reported the ticket.
    id: plan_enhancement
    label: Plan Enhancement
```
::

When the team agrees with the plan, a comment that mentions the Knecht account, such as "implement it and open a PR", is enough. Knecht continues in the same session and answers with the pull request.

::note
A ticket that a person labels and moves to "To Do" without the triage having seen it starts these workflows without a booted site. Add a boot step to them if that happens in your team.
::

### Assign to Knecht

No label and no triage: the team assigns a ticket to the Knecht account like to any colleague, and Knecht implements it. This workflow stands on its own, so it boots the site itself.

| Source | Fires When         | But Only If               |
| ------ | ------------------ | ------------------------- |
| Jira   | Assigned to Knecht | Issue type is `Bug, Task` |

::docs-workflow-yaml{filename="jira-assigned-ticket.yaml"}
```yaml
version: 1
name: Jira Assigned Ticket
description: Implement a ticket that was assigned to Knecht.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: The ticket of this session was assigned to you. Read it with its
      comments, implement it on a work branch, verify it on the preview, commit,
      and open a pull request. Comment a short summary on the ticket and move it
      to "In Review".
    id: implement
    label: Implement
```
::

### Estimate Tickets

A ticket that is moved to "In Planning" gets an estimate and lands in "To Do". The agent reads the ticket, looks up the code it touches, and comments how big the work is and why. An estimate needs the code, not the running site, so there is no boot step. Pick the exact status of your board in the trigger, the names here are examples.

| Source | Fires When                  | But Only If   |
| ------ | --------------------------- | ------------- |
| Jira   | Status reached: In Planning | No conditions |

::docs-workflow-yaml{filename="jira-estimate-ticket.yaml"}
```yaml
version: 1
name: Jira Estimate Ticket
description: Estimate a ticket in planning and move it to To Do.
steps:
  - type: ai
    prompt: 'Estimate the ticket of this session. Find the code it touches and judge
      the effort. Do not change any files. Comment the estimate on the ticket: a
      size (S, M, L, or XL), the hours you expect, what drives the effort, and
      what is unclear. Then move the ticket to "To Do". If it is too vague to
      estimate, comment your questions and leave it where it is.'
    id: estimate
    label: Estimate
```
::


# Plane

The Plane integration connects a Plane workspace to your instance, on Plane Cloud or self-hosted. Work items start workflows, the agent reads and answers on them, moves them between states, and Knecht reports the finished pull request back on the work item.

## Setup

You need a Plane workspace and an account Knecht acts as. A dedicated account named "Knecht" is worth the extra seat: comments show up under its name, "assign it to Knecht" becomes a normal assignment in Plane, and the account's project memberships limit what Knecht can see. Creating the webhook in step three needs workspace admin rights, once.

::steps{level="3"}
### Create a Personal Access Token

Sign in to Plane as the account Knecht should use and open the profile settings. Under Developer, "Personal Access Tokens", click "Add access token". Give it a title such as "Knecht", leave "Never expires" on or set an expiration date, and click "Generate token". Copy the token, it starts with `plane_api_` and is shown only once.

![The Create token dialog in the Plane profile settings, with the title Knecht and Never expires switched on](https://knecht.works/assets/plane-access-token.png)

A token with an expiration date stops working on that day. Create a new one and use "Reconnect" in Knecht before it runs out.

### Connect the Account

In your instance, open Settings, Integrations. The Plane panel has three fields:

- **Plane URL.** `https://app.plane.so` for Plane Cloud, or the address of your own Plane. It has to start with `https://`.
- **Workspace slug.** The first path segment of your Plane URL. For `https://app.plane.so/acme/projects` it is `acme`.
- **API key.** The token from step one.

"Connect" checks the credentials against Plane before anything is stored and shows "Connected as" with the account's name on success. The token is stored encrypted and not shown again. "Reconnect" replaces the token later, "Disconnect" removes the connection.

![The Plane panel under Settings, Integrations, connected to an account, with the Plane URL, workspace slug, and API key fields, and the webhook URL and secret below](https://knecht.works/assets/knecht-integration-settings-plane.png)

### Create the Webhook in Plane

Plane does not call Knecht until you tell it to. After connecting, the panel shows "Create the webhook in Plane and paste its secret below" with the webhook URL and a copy button. "Set up in Plane" opens the webhook page of your workspace. By hand it is Workspace settings, then "Webhooks" under Developers.

Fill in the form:

- **Webhook title.** Anything, for example "Knecht".
- **Payload URL.** The webhook URL from the panel, it ends in `/api/plane/webhook`.
- **V1 scopes.** Leave everything unticked, they are deprecated.
- **V2 scopes.** Tick "Work items" and "Work item comments". Everything else stays empty.
- **Work item v2 filters.** Leave it empty. Knecht drops events of projects that are not linked.

![The Create webhook form in the Plane workspace settings, with the Knecht payload URL and the V2 scopes Work items and Work item comments ticked](https://knecht.works/assets/plane-webhook-events.png)

Knecht uses the work item events created, updated, archived, and deleted, and the comment event created. Updated and deleted comments arrive as well and are ignored.

"Create" saves the webhook, and Plane generates a secret key for it. Copy the secret key, paste it into the Secret field of the Plane panel in Knecht, and click "Save". The pencil next to the secret replaces it later, for example after regenerating the key in Plane. The status line switches to "Waiting for Plane".

### Link a Project to Its Plane Project

Open the settings of a project in Knecht. The Plane panel has one field, "Plane project", listing the projects the account is a member of. Pick the one whose work items belong to this repository. One Plane project links to one repository and the other way round. Only linked projects can have Plane triggers.

### Check That Events Arrive

Edit any work item in the linked Plane project. The status line in the Plane panel under Settings, Integrations switches to "Receiving events" with the last event and work item key. If it does not:

| Status line says          | What to do                                                                                                      |
| ------------------------- | --------------------------------------------------------------------------------------------------------------- |
| Wrong secret              | Replace the secret in the panel with the secret key of the webhook.                                             |
| Without a body            | Create the webhook again, Plane sent an empty delivery.                                                         |
| No project is linked      | Link the Plane project in the project settings, see step four. Events Knecht does not use show up here as well. |
| Still "Waiting for Plane" | Check that the webhook URL is reachable from the internet and that the scopes are ticked.                       |
::

## Capabilities

### Triggers

A Plane trigger watches the Plane projects that are linked to the selected projects. When a work item fires it, one run starts in the project that work item's Plane project is linked to. The project field only lists projects that are linked. In the form, "Fires when any of these happens" lists the events and "But only if" the conditions. Any ticked event fires the trigger, and one group of conditions has to hold. How the two sections work in general is on [Triggers](https://knecht.works/docs/usage/triggers#events-and-conditions). What all issue trackers share, such as issues that are created with the label already set, is on [Triggers](https://knecht.works/docs/usage/triggers#issue-trackers).

![The trigger dialog with Plane selected as source, one linked project, the event Assigned to Knecht ticked, and the conditions Label is Bug and Priority is urgent](https://knecht.works/assets/knecht-trigger-plane.png)

#### Events

| Event              | Fires when                                                       | Notes                                                                                                                                                                             |
| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Created            | A new work item appears in the project.                          |                                                                                                                                                                                   |
| Assigned to Knecht | The work item is assigned to the account behind the connection.  | Ticked by default. Makes "give it to Knecht" a normal assignment in Plane. Knecht [joining the assignees](https://knecht.works/#knecht-holds-the-work-item) itself does not fire. |
| Label added        | One of the picked labels is added to a work item.                | The labels are picked from the labels of the Plane project.                                                                                                                       |
| State reached      | A work item moves into one of the picked states or state groups. | The default is "Any Completed". A work item created in a state does not fire.                                                                                                     |

#### State Reached

The state list has two groups.

- **Group.** "Any Backlog", "Any Unstarted", "Any Started", "Any Completed", and "Any Cancelled" stand for Plane's five state groups, whatever the states of a project are called.
- **Exact state.** The states of the selected projects.

[Triggers](https://knecht.works/docs/usage/triggers#issue-trackers) explains when a group and when an exact state fires, [Matching](https://knecht.works/docs/usage/triggers#matching) what happens with several projects. If the form warns about a missing state, pick a group, a state all projects share, or create a second trigger.

#### Conditions

| Field    | Compares against                                                                   |
| -------- | ---------------------------------------------------------------------------------- |
| State    | The state the work item is in, as a group such as "Any Started" or an exact state. |
| Assignee | "Knecht", the account behind the connection.                                       |
| Label    | The labels on the work item, read from the Plane project.                          |
| Priority | The priority of the work item: `urgent`, `high`, `medium`, `low`, or `none`.       |

Each condition takes "is" or "is not". Every value is picked from a list and compared exactly, upper and lower case included. The rules are the same for every source, see [Matching](https://knecht.works/docs/usage/triggers#matching).

#### Inputs

The work item fills the run inputs: `identifier` is the key such as `WEB-42`, `title` the name, `body` the description converted to Markdown, `url` the work item link, `status` the state name, `labels` the labels, `assignee` and `author` the names of the assignees and the creator. `event` is `issue`. Pausing, versioning, and shared behavior are on [Triggers](https://knecht.works/docs/usage/triggers).

### Sessions on Work Items

A run started by a work item joins the [session](https://knecht.works/docs/get-started/concepts#sessions) of that work item, like a run on a GitHub issue. The session keeps the checkout, the environment, and the agent conversation, so a second trigger on the same work item or a mention continues the work. The session closes when the work item reaches a state in the Completed or Cancelled group, is archived, or is deleted, its environment stops once no run needs it any more, and it opens again when the work item is moved back.

### Knecht Holds the Work Item

Knecht joins the assignees of a work item while it works on it, as on every issue tracker, see [Triggers](https://knecht.works/docs/usage/triggers#knecht-holds-the-issue). A work item takes several assignees, so the people already on it stay on it, and when Knecht leaves, they keep the work item. If Knecht was the only assignee, the work item goes to the person whose change started the run, else to the creator, else it is left unassigned.

### The Agent on Work Items

When the run's session belongs to a work item, the [agent](https://knecht.works/docs/usage/agent) gets four commands inside the environment. The prompt of an AI step only has to name what to do with them.

- **Read the work item.** State, creator, assignees, labels, the description, and the last ten comments, live from Plane.
- **Reply.** Posts a comment on the work item. The agent writes Markdown, Knecht converts it to Plane's format and appends the preview link and, when one exists, the pull request link. An `@Name` of a project member becomes a real mention that notifies that person.
- **Set labels.** Adds or removes labels of the Plane project. Knecht never creates labels. If a name does not exist, the agent gets the list of existing labels instead.
- **Move the work item.** Sets the state by name, for example "In Review". Plane has no transition rules, so every state of the project is reachable.

Opening a pull request works through the git steps or the agent's own command, see [GitHub](https://knecht.works/docs/integrations/github#workflow-steps).

### Mentions

Write a comment on a work item of a linked Plane project, mention the Knecht account the way you mention a colleague, and add the instruction:

```text
@Knecht fix the broken footer link
```

`@knecht` typed as plain text works as well. Knecht runs the comment as a follow-up and posts the answer as a comment.

Whoever can comment on the work item can mention Knecht, the Plane workspace is the gate.

The one-time setup, what happens step by step, and what to check when Knecht stays silent is on [Mentions](https://knecht.works/docs/usage/agent#mentions).

## Examples

The workflows below can be built in the editor or imported from YAML under Workflows, "Import". Triggers are added in the editor after the import. All of them assume the project is linked to its Plane project.

### Software Factory

Three workflows that hand a work item from one to the next. The triage checks every new work item, sets the label `Bug` or `Enhancement`, and moves it to "Todo". That move fires the trigger of the workflow whose label condition matches. A bug comes back with a pull request and a work item in review, an enhancement with a plan that a mention in the comments turns into a pull request.

All of it runs in the [session](https://knecht.works/#sessions-on-work-items) of the work item. The triage boots the site once and every later run finds it running, so only the triage has a boot step. The prompts do not repeat name or description, because the agent reads the work item of its session itself.

::note
Plane creates the label `Bug` with every project, add `Enhancement` under the project settings, "Labels", first. Knecht only applies labels that exist, and a trigger only offers labels that exist. The state "In Review" is not a default either: add it under "States" in the Started group, a state in the Completed group would close the session.
::

#### Triage

| Source | Fires When | But Only If   |
| ------ | ---------- | ------------- |
| Plane  | Created    | No conditions |

::docs-workflow-yaml{filename="plane-work-item-triage.yaml"}
```yaml
version: 1
name: Plane Work Item Triage
description: Check every new work item and label it as bug or enhancement.
steps:
  - type: ddev-start
    id: boot_project
  - type: ai
    prompt: >-
      Read the work item of this session. Try to reproduce it in the preview and
      in the code. Do not fix anything. Then apply exactly one label: "Bug" if
      something is broken, "Enhancement" if it was never built and then move it
      to "Todo".

      If the work item lacks the details to decide, apply no label and ask the
      creator in a comment for clarification.
    id: triage
    label: Triage
```
::

#### Bug Fix

| Source | Fires When            | But Only If    |
| ------ | --------------------- | -------------- |
| Plane  | State reached: `Todo` | Label is `Bug` |

::docs-workflow-yaml{filename="plane-bug-fix.yaml"}
```yaml
version: 1
name: Plane Bug Fix
description: Fix a work item labeled as bug and open a pull request.
steps:
  - type: ai
    prompt: >-
      The work item of this session was confirmed as a bug. When you are
      beginning your work move the work item to "In Progress". Then fix it on a
      work branch, verify the fix on the preview, commit in logical batches, and
      open a pull request.

      Comment a short summary of the change on the work item and move it to "In
      Review".
    id: bug_fix
    label: Bug Fix
```
::

#### Add Enhancement

| Source | Fires When            | But Only If            |
| ------ | --------------------- | ---------------------- |
| Plane  | State reached: `Todo` | Label is `Enhancement` |

::docs-workflow-yaml{filename="plane-add-enhancement.yaml"}
```yaml
version: 1
name: Plane Add Enhancement
description: Plan a work item labeled as enhancement and post the plan.
steps:
  - type: ai
    prompt: >-
      The work item of this session is an enhancement.

      Work out how it would be built in this project: the files to touch, the
      steps in order, and what is open.

      Do not change any files or the state. Just post the plan as a comment,
      written for the person who created the work item.
    id: plan_enhancement
    label: Plan Enhancement
```
::

When the team agrees with the plan, a comment that mentions the Knecht account, such as "implement it and open a PR", is enough. Knecht continues in the same session and answers with the pull request.

::note
A work item that a person labels and moves to "Todo" without the triage having seen it starts these workflows without a booted site. Add a boot step to them if that happens in your team.
::

### Urgent Bugs to Knecht

No triage: the team assigns a work item to the Knecht account like to any colleague, and Knecht implements it. The conditions keep it to urgent bugs, everything else assigned to Knecht stays untouched. This workflow stands on its own, so it boots the site itself.

| Source | Fires When         | But Only If                             |
| ------ | ------------------ | --------------------------------------- |
| Plane  | Assigned to Knecht | Label is `Bug` and Priority is `urgent` |

::docs-workflow-yaml{filename="plane-assigned-work-item.yaml"}
```yaml
version: 1
name: Plane Assigned Work Item
description: Implement a work item that was assigned to Knecht.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: The work item of this session was assigned to you. Read it with its
      comments, implement it on a work branch, verify it on the preview, commit,
      and open a pull request. Comment a short summary on the work item and move
      it to "In Review".
    id: implement
    label: Implement
```
::

### Estimate Work Items

A work item that is moved to "In Planning" gets an estimate and lands in "Todo". The agent reads the work item, looks up the code it touches, and comments how big the work is and why. An estimate needs the code, not the running site, so there is no boot step. Pick the exact state of your project in the trigger, the names here are examples.

| Source | Fires When                 | But Only If   |
| ------ | -------------------------- | ------------- |
| Plane  | State reached: In Planning | No conditions |

::docs-workflow-yaml{filename="plane-estimate-work-item.yaml"}
```yaml
version: 1
name: Plane Estimate Work Item
description: Estimate a work item in planning and move it to Todo.
steps:
  - type: ai
    prompt: 'Estimate the work item of this session. Find the code it touches and
      judge the effort. Do not change any files. Comment the estimate on the
      work item: a size (S, M, L, or XL), the hours you expect, what drives the
      effort, and what is unclear. Then move the work item to "Todo". If it is
      too vague to estimate, comment your questions and leave it where it is.'
    id: estimate
    label: Estimate
```
::


# Linear

The Linear integration connects a Linear workspace to your instance. Issues start workflows, the agent reads and answers on them, moves them between statuses, and Knecht reports the finished pull request back on the issue.

## Setup

You need a Linear workspace and an account Knecht acts as. A dedicated account named "Knecht" is worth the extra seat: comments show up under its name, "assign it to Knecht" becomes a normal assignment in Linear, and the account's team memberships limit what Knecht can see. Creating the webhook in step three needs workspace admin rights, once.

::steps{level="3"}
### Create a Personal API Key

Sign in to Linear as the account Knecht should use and open Settings, "Security & access". Under "Personal API keys", create a new key. Give it a name such as "Knecht" and fill in the form:

- **Permissions.** "Full access", or under "Only select permissions" at least Read and Write. Knecht reads issues and comments, writes comments, and changes labels and statuses.
- **Team access.** "All teams you have access to", or under "Only select teams" the teams you want to link to projects.

![The Create API key form in the Linear security settings, with the key name Knecht, Full access, and All teams you have access to selected](https://knecht.works/assets/linear-api-key.png)

"Create" shows the key. Copy it, it starts with `lin_api_` and is shown only once. Everything Knecht does with the key is attributed to this account.

### Connect the Account

In your instance, open Settings, Integrations. The Linear panel has one field, "API key", for the key from step one.

"Connect" checks the key against Linear before anything is stored and shows "Connected as" with the account's name on success. The key is stored encrypted and not shown again. "Reconnect" replaces the key later, "Disconnect" removes the connection.

![The Linear panel under Settings, Integrations, connected to an account, with the API key field, and the webhook URL and secret below](https://knecht.works/assets/knecht-integration-settings-linear.png)

### Create the Webhook in Linear

Linear does not call Knecht until you tell it to. After connecting, the panel shows the webhook URL with a copy button. "Set up in Linear" opens the API settings of your workspace. By hand it is Settings, then "API" under Administration, then "Webhooks".

Fill in the form:

- **Label.** Anything, for example "Knecht".
- **URL.** The webhook URL from the panel, it ends in `/api/linear/webhook`.
- **Data change events.** Tick "Issues" and "Comments". Everything else stays empty.
- **Other events.** Leave "Issue SLA" unticked.
- **Team selection.** "All public teams", or the one team you link. It cannot be changed after creation. Knecht drops events of teams that are not linked.

![The Create webhook form in the Linear API settings, with the Knecht webhook URL and the data change events Comments and Issues ticked](https://knecht.works/assets/linear-webhook-events.png)

Knecht uses the issue events create, update, and remove, and the comment event create. Updated and removed comments arrive as well and are ignored.

The form already shows the signing secret, it starts with `lin_wh_`. Copy it, click "Create webhook", paste the secret into the Secret field of the Linear panel in Knecht, and click "Save". Unlike Jira, the secret comes from Linear, not from Knecht. Knecht keeps one signing secret, so use one webhook for all linked teams. The pencil next to the secret replaces it later. The status line switches to "Waiting for Linear".

### Link a Project to Its Linear Team

Open the settings of a project in Knecht. The Linear panel has one field, "Linear team", listing the teams the account can access. Pick the one whose issues belong to this repository. One Linear team links to one repository and the other way round. Only linked projects can have Linear triggers.

### Check That Events Arrive

Edit any issue of the linked team. The status line in the Linear panel under Settings, Integrations switches to "Receiving events" with the last event and issue identifier. If it does not:

| Status line says           | What to do                                                                                                                                 |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Wrong secret               | Replace the secret in the panel with the signing secret of the webhook.                                                                    |
| Without a body             | Create the webhook again, Linear sent an empty delivery.                                                                                   |
| No project is linked       | Link the Linear team in the project settings, see step four. Events Knecht does not use show up here as well.                              |
| Still "Waiting for Linear" | Check that the webhook URL is reachable from the internet, that the events are ticked, and that the team selection covers the linked team. |
::

## Capabilities

### Triggers

A Linear trigger watches the Linear teams linked to the selected projects and starts one run for the project whose team the issue belongs to. The project field only lists projects that are linked. In the form, "Fires when any of these happens" lists the events and "But only if" the conditions. Any ticked event fires the trigger, and one group of conditions has to hold. How the two sections work in general is on [Triggers](https://knecht.works/docs/usage/triggers#events-and-conditions). What all issue trackers share, such as issues that are created with the label already set, is on [Triggers](https://knecht.works/docs/usage/triggers#issue-trackers).

![The trigger dialog with Linear selected as source, one linked project, the event Created ticked, and the condition Status is Any Triage](https://knecht.works/assets/knecht-trigger-linear.png)

#### Events

| Event              | Fires when                                                           | Notes                                                                                                                                                                                                      |
| ------------------ | -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Created            | A new issue appears in the team.                                     |                                                                                                                                                                                                            |
| Assigned to Knecht | The issue is assigned to the account behind the connection.          | Ticked by default. Makes "give it to Knecht" a normal assignment in Linear. Knecht taking the issue itself does not fire, see [Triggers](https://knecht.works/docs/usage/triggers#knecht-holds-the-issue). |
| Label added        | One of the picked labels is added to an issue.                       | The labels are picked from the labels of the team and the workspace. Label groups are not listed, they cannot be applied themselves.                                                                       |
| Status reached     | An issue moves into one of the picked statuses or status categories. | The default is "Any Completed". An issue created in a status does not fire.                                                                                                                                |

#### Status Reached

The status list has two groups.

- **Category.** "Any Triage", "Any Backlog", "Any Unstarted", "Any Started", "Any Completed", and "Any Canceled" stand for Linear's six status categories, whatever the statuses of a team are called.
- **Exact status.** The statuses of the selected teams.

[Triggers](https://knecht.works/docs/usage/triggers#issue-trackers) explains when a category and when an exact status fires, [Matching](https://knecht.works/docs/usage/triggers#matching) what happens with several projects. If the form warns about a missing status, pick a category, a status all teams share, or create a second trigger.

#### Conditions

| Field    | Compares against                                                                   |
| -------- | ---------------------------------------------------------------------------------- |
| Status   | The status the issue is in, as a category such as "Any Triage" or an exact status. |
| Assignee | "Knecht", the account behind the connection.                                       |
| Label    | The labels on the issue, read from the team and the workspace.                     |
| Priority | The priority of the issue: `urgent`, `high`, `medium`, `low`, or `none`.           |

Each condition takes "is" or "is not". Every value is picked from a list and compared exactly, upper and lower case included. The rules are the same for every source, see [Matching](https://knecht.works/docs/usage/triggers#matching).

#### Inputs

The issue fills the run inputs: `identifier` is the key such as `ENG-42`, `title` the title, `body` the description as Markdown, `url` the issue link, `status` the status name, `labels` the labels, `assignee` and `author` the names of the assignee and the creator. `event` is `issue`. Pausing, versioning, and shared behavior are on [Triggers](https://knecht.works/docs/usage/triggers).

### Sessions on Issues

A run started by an issue joins the [session](https://knecht.works/docs/get-started/concepts#sessions) of that issue, like a run on a GitHub issue. The session keeps the checkout, the environment, and the agent conversation, so a second trigger on the same issue or a mention continues the work. The session closes when the issue reaches a status in the Completed or Canceled category, is archived, or is deleted, its environment stops once no run needs it any more, and it opens again when the issue is moved back.

### The Agent on Issues

When the run's session belongs to an issue, the [agent](https://knecht.works/docs/usage/agent) gets four commands inside the environment. The prompt of an AI step only has to name what to do with them.

- **Read the issue.** Priority, status, creator, assignee, labels, the description, and the last ten comments, live from Linear.
- **Reply.** Posts a comment on the issue. The agent writes Markdown, which Linear takes as it is, and Knecht appends the preview link and, when one exists, the pull request link.
- **Set labels.** Adds or removes labels of the team and the workspace. Knecht never creates labels. If a name does not exist, the agent gets the list of existing labels instead.
- **Move the issue.** Sets the status by name, for example "In Review". Linear has no transition rules, so every status of the team is reachable.

Opening a pull request works through the git steps or the agent's own command, see [GitHub](https://knecht.works/docs/integrations/github#workflow-steps).

### Mentions

Write a comment on an issue of a linked Linear team, mention the Knecht account the way you mention a colleague, and add the instruction:

```text
@Knecht fix the broken footer link
```

`@knecht` typed as plain text works as well. Knecht runs the comment as a follow-up and posts the answer as a comment.

Whoever can comment on the issue can mention Knecht, the Linear workspace is the gate.

The one-time setup, what happens step by step, and what to check when Knecht stays silent is on [Mentions](https://knecht.works/docs/usage/agent#mentions).

## Examples

The workflows below can be built in the editor or imported from YAML under Workflows, "Import". Triggers are added in the editor after the import. All of them assume the project is linked to its Linear team.

### Software Factory

Three workflows that hand an issue from one to the next. The triage checks every new issue, sets the label `Bug` or `Feature`, and moves it to "Todo". That move fires the trigger of the workflow whose label condition matches. A bug comes back with a pull request and an issue in review, a feature with a plan that a mention in the comments turns into a pull request.

All of it runs in the [session](https://knecht.works/#sessions-on-issues) of the issue. The triage boots the site once and every later run finds it running, so only the triage has a boot step. The prompts do not repeat title or description, because the agent reads the issue of its session itself.

::note
Make sure the labels `Bug` and `Feature` exist in the team or the workspace first. Knecht only applies labels that exist, and a trigger only offers labels that exist.
::

#### Triage

| Source | Fires When | But Only If   |
| ------ | ---------- | ------------- |
| Linear | Created    | No conditions |

::docs-workflow-yaml{filename="linear-issue-triage.yaml"}
```yaml
version: 1
name: Linear Issue Triage
description: Check every new issue and label it as bug or feature.
steps:
  - type: ddev-start
    id: boot_project
  - type: ai
    prompt: >-
      Read the issue of this session. Try to reproduce it in the preview and in
      the code. Do not fix anything. Then apply exactly one label: "Bug" if
      something is broken, "Feature" if it was never built and then move it to
      "Todo".

      If the issue lacks the details to decide, apply no label and ask the
      creator in a comment for clarification.
    id: triage
    label: Triage
```
::

#### Bug Fix

| Source | Fires When             | But Only If    |
| ------ | ---------------------- | -------------- |
| Linear | Status reached: `Todo` | Label is `Bug` |

::docs-workflow-yaml{filename="linear-bug-fix.yaml"}
```yaml
version: 1
name: Linear Bug Fix
description: Fix an issue labeled as bug and open a pull request.
steps:
  - type: ai
    prompt: >-
      The issue of this session was confirmed as a bug. When you are beginning
      your work move the issue to "In Progress". Then fix it on a work branch,
      verify the fix on the preview, commit in logical batches, and open a pull
      request.

      Comment a short summary of the change on the issue and move it to "In
      Review".
    id: bug_fix
    label: Bug Fix
```
::

#### Plan Feature

| Source | Fires When             | But Only If        |
| ------ | ---------------------- | ------------------ |
| Linear | Status reached: `Todo` | Label is `Feature` |

::docs-workflow-yaml{filename="linear-plan-feature.yaml"}
```yaml
version: 1
name: Linear Plan Feature
description: Plan an issue labeled as feature and post the plan.
steps:
  - type: ai
    prompt: >-
      The issue of this session is a feature.

      Work out how it would be built in this project: the files to touch, the
      steps in order, and what is open.

      Do not change any files or the status. Just post the plan as a comment,
      written for the person who created the issue.
    id: plan_feature
    label: Plan Feature
```
::

When the team agrees with the plan, a comment that mentions the Knecht account, such as "implement it and open a PR", is enough. Knecht continues in the same session and answers with the pull request.

::note
An issue that a person labels and moves to "Todo" without the triage having seen it starts these workflows without a booted site. Add a boot step to them if that happens in your team.
::

### Urgent Bugs to Knecht

No triage: the team assigns an issue to the Knecht account like to any colleague, and Knecht implements it. The conditions keep it to urgent bugs, everything else assigned to Knecht stays untouched. This workflow stands on its own, so it boots the site itself.

| Source | Fires When         | But Only If                             |
| ------ | ------------------ | --------------------------------------- |
| Linear | Assigned to Knecht | Label is `Bug` and Priority is `urgent` |

::docs-workflow-yaml{filename="linear-assigned-issue.yaml"}
```yaml
version: 1
name: Linear Assigned Issue
description: Implement an issue that was assigned to Knecht.
steps:
  - type: ddev-start
    id: boot_project
    label: Boot the Site
  - type: ai
    prompt: The issue of this session was assigned to you. Read it with its
      comments, implement it on a work branch, verify it on the preview, commit,
      and open a pull request. Comment a short summary on the issue and move it
      to "In Review".
    id: implement
    label: Implement
```
::

### Estimate the Triage Inbox

With Triage switched on for a team, issues from other tools and from people outside the team land in the Triage status first. This workflow gives each of them an estimate and moves it to "Backlog". A new issue is created in Triage and does not move there, so the trigger fires on "Created" with a condition on the status instead of on "Status reached". The agent reads the issue, looks up the code it touches, and comments how big the work is and why. An estimate needs the code, not the running site, so there is no boot step.

| Source | Fires When | But Only If          |
| ------ | ---------- | -------------------- |
| Linear | Created    | Status is Any Triage |

::docs-workflow-yaml{filename="linear-estimate-issue.yaml"}
```yaml
version: 1
name: Linear Estimate Issue
description: Estimate an issue in triage and move it to Backlog.
steps:
  - type: ai
    prompt: 'Estimate the issue of this session. Find the code it touches and judge
      the effort. Do not change any files. Comment the estimate on the issue: a
      size (S, M, L, or XL), the hours you expect, what drives the effort, and
      what is unclear. Then move the issue to "Backlog". If it is too vague to
      estimate, comment your questions and leave it where it is.'
    id: estimate
    label: Estimate
```
::


# Beta Testers

Knecht is in a closed beta. This page covers what happens after you've applied: getting an instance, setting it up, and redeeming your OpenCode credit.

## Managed or Self-Hosted

Before anything else, decide where your instance runs. Both options are the same software with the same setup flow, GitHub App, and updates. The difference is who operates the server and where your data lives.

|                 | Managed                                              | Self-hosted                                             |
| --------------- | ---------------------------------------------------- | ------------------------------------------------------- |
| Server          | A machine we operate                                 | Your own, a fresh Ubuntu 24.04 VPS or a Mac             |
| Getting started | You receive a URL from us                            | You run the install script, a few minutes               |
| Updates         | We apply them                                        | You do, by a button on the System page or on a schedule |
| Your data       | Repositories, env files, and dumps sit on our server | Everything stays on your infrastructure                 |
| Availability    | Limited number of instances during the beta          | Unlimited                                               |

Pick managed if you want to test Knecht without touching a server. Pick self-hosted if your projects' data must not leave your infrastructure, or if you want to evaluate the install and update experience as well. [Installation](https://knecht.works/docs/get-started/installation) lists the server requirements, [Maintenance](https://knecht.works/docs/get-started/maintenance) what running it involves. Tell us which one you want in the mail after your application.

## How Onboarding Works

::steps{level="3"}
### Get an Instance

With managed hosting, you receive the URL of your instance from us and skip ahead. For a self-hosted instance, follow [Installation](https://knecht.works/docs/get-started/installation) on a fresh server. Both end at the same point: the dashboard is reachable under its domain.

### Set up the Instance

The first visit creates the GitHub App and signs you in. [Setup](https://knecht.works/docs/get-started/setup) walks through it, including inviting your team.

### Add the First Project

Connect a repository, paste its env, upload a database dump, and boot it. [Projects](https://knecht.works/docs/usage/projects) covers the guided setup and what the project page offers afterward.
::

## Getting Your OpenCode Credit

The credit lives in an OpenCode workspace we manage. You do not need an OpenCode account of your own:

::steps{level="3"}
### Receive the Key

We create a key for you in our workspace and send it to you. It starts with `oc_sk_` and is capped at your credit.

### Enter the Key in Knecht

In your instance, open Settings > Agent. Pick "OpenCode Zen" as the provider, paste the key, and choose a default model from the list.
::

::warning
Pick "OpenCode Zen", not "OpenCode Go". The credit is on Zen, and a Go model fails with this key.
::

::note
Keys from the old OpenCode console, starting with `sk-`, no longer work. If your instance still uses one, write to <hallo@knecht.works> and we send you a new key.
::


# Troubleshooting

Most projects boot on Knecht exactly as they do with [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} locally. If yours doesn't, check the cases below, the exceptions we have met so far. Almost all of them share one cause: Knecht routes previews by hostname on one port, while the DDEV router convention puts a dev server on the same host and another port. A Vite dev server on Knecht therefore has its own origin, handed to the project as `KNECHT_DEV_SERVER_URL`. Any config that builds a "same host, other port" address needs to read that variable instead.

::note
All fixes on this page are on the project side and leave local development unchanged. `KNECHT_DEV_SERVER_URL` is simply unset on your machine, so every fallback keeps working as before. After changing a Vite config, restart the session's dev server so the marker files are rewritten.
::

## Laravel

### Vite Origin from DDEV\_PRIMARY\_URL

**Symptom.** The preview loads, but `/@vite/client`, `app.css`, and `app.js` fail. The tags point at the preview host on port 5173.

**Cause.** `vite.config.js` builds `server.origin` from `DDEV_PRIMARY_URL` plus `:5173`. The Laravel Vite plugin writes that origin into `public/hot`, and Blade emits it verbatim. No value of `DDEV_PRIMARY_URL` makes "same host, other port" reachable on Knecht.

**Fix.** Prefer the Knecht variable and keep the DDEV branch as fallback:

```js
server: {
  origin: process.env.KNECHT_DEV_SERVER_URL
    ?? (process.env.DDEV_PRIMARY_URL
      ? `${process.env.DDEV_PRIMARY_URL.replace(/:\d+$/, '')}:5173`
      : undefined),
},
```

## Drupal

### Dev/Dist Decision Cached Too Early

**Symptom.** A preview with a dev server configured still loads `/dist/assets/...`, without `/@vite/client` or HMR. Or the tags point at `http://localhost:5173`.

**Cause.** The `drupal/vite` module decides between dev server and dist build in `hook_library_info_alter`, so the decision is taken at `drush cr` and cached. With the default `useDevServer: auto`, it probes the dev server from PHP at that moment. The boot commands run `drush cr` before the dev server is up, so the probe fails and "dist" is cached. When the probe does hit, the default `devServerUrl` of `http://localhost:5173` ends up in the HTML. The module also ignores Vite's `base`, so a `base: '/dist/'` config 404s on the dev server.

**Fix.** Switch explicitly in `settings.php` when Knecht hands the URL in, no probe involved:

```php
if ($dev = getenv('KNECHT_DEV_SERVER_URL')) {
  $settings['vite'] = ['useDevServer' => TRUE, 'devServerUrl' => rtrim($dev, '/')];
}
```

In `vite.config.js`, set the base per mode: `base: command === 'serve' ? '/' : '/dist/'`. Run `drush cr` once after the change in a running session.

## Kirby

### Dev Server Origin Defaults to 0.0.0.0

**Symptom.** The preview loads, but `/@vite/client` and the app's CSS and JS are requested from `http://0.0.0.0:5173`, which the browser blocks.

**Cause.** kirby-vite switches to the dev server as soon as a `.dev` marker file exists and reads the browser-facing URL from it. vite-plugin-kirby writes that file when Vite starts, with `server.origin` or, when none is set, with `<protocol>://<host>:<port>`, which is `http://0.0.0.0:5173` for a server bound to all interfaces.

**Fix.** One line in `vite.config.js`:

```js
server: {
  origin: process.env.KNECHT_DEV_SERVER_URL,
},
```

## Craft

### devServerPublic Is a Literal DDEV URL

**Symptom.** The preview loads, but its module scripts point at `https://<project>.ddev.site:3000/`, which the browser cannot reach.

**Cause.** `config/vite.php` carries the browser-facing dev server URL as a literal, the DDEV router convention. Nothing in the Craft Vite plugin derives it from the request or from env. A second gate is `useDevServer`, usually `CRAFT_ENVIRONMENT === 'dev'`, so that variable has to be set on Knecht too.

**Fix.** Read `devServerPublic` from env with a trailing slash and keep the DDEV URL as local fallback:

```php
'devServerPublic' => App::env('KNECHT_DEV_SERVER_URL')
    ? rtrim(App::env('KNECHT_DEV_SERVER_URL'), '/') . '/'
    : 'https://myproject.ddev.site:3000/',
```

`devServerInternal` stays `http://localhost:3000`, Craft probes it from PHP inside the same container. Add `CRAFT_ENVIRONMENT=dev` to the project's environment variables in Knecht.

## Custom Vite Setups

### No Dev Branch at All

**Symptom.** The preview keeps loading `/dist/assets/...`, or shows a "no manifest entry" comment, whatever the dev server does.

**Cause.** A hand-rolled loader reads `dist/.vite/manifest.json` and nothing else. There is no plugin that knows about a dev server, so nothing ever emits `/@vite/client`. Often the Vite config pins no port either, and a `base: '/dist/'` puts the dev URLs under `/dist/`.

**Fix.** Branch in the loader: when `KNECHT_DEV_SERVER_URL` is set, emit the HMR client once plus a `<link>` and a `<script type="module">` for the entry from that origin, otherwise the manifest path as before. In `vite.config.js`, pin the port and serve from the root in dev mode:

```js
export default defineConfig(({ command }) => ({
  base: command === 'serve' ? '/' : '/dist/',
  server: { port: 5173, strictPort: true },
}))
```

Hit a project that behaves differently from your local setup and is not listed here? Tell us on [Discord](https://discord.gg/WuxjmtgUyX){rel="&#x22;nofollow&#x22;"} or at <hallo@knecht.works>, ideally with the symptom and the relevant config file.


# Privacy Policy

## Controller

The controller responsible for data processing on this website is:

Email: <hallo@knecht.works>

## Collection and processing of personal data

We process personal data only as far as this is necessary to provide a
functional website and our content and services.

## Waitlist / Newsletter

If you join the waitlist, we process your email address only to send you
product updates and beta information. You can withdraw your consent at any
time with effect for the future.

## Your rights

You have the right to access, rectification, erasure, restriction of
processing, data portability, and objection to processing.

## Hosting

This website is hosted by [Cloudflare](https://cloudflare.com){rel="&#x22;nofollow&#x22;"}. For details about data processing
by this provider, see its privacy policy.


# Legal Notice (Impressum)

## Information according to § 5 TMG (German Telemedia Act)

**Knecht**:br
Leonfeldner Straße 90a :br
4040 Linz :br

## Contact

Email: <hallo@knecht.works>

## Represented by

[Samuel Reichör](https://samuelreichor.at){rel="&#x22;nofollow&#x22;"}:br
Leonfeldner Straße 90a :br
4040 Linz :br

## VAT ID

VAT identification number according to § 27a Umsatzsteuergesetz (VAT Act):

VAT ID: ATU82964259
Tax number: 52 392/4660


# The Agent Gets a Memory per Project

The [AI action](https://knecht.works/updates/workflow-engine) starts a fresh [sandbox](https://knecht.works/updates/sandbox-rollback) for every run, with its own checkout of the project. Until now the agent knew nothing about earlier runs. What it had found out about a project was gone afterwards, and the next run had to explore it again. Now Knecht keeps notes per project. The agent writes them itself and finds them again in the next run.

## Every run started at zero

In August 2026 we looked at where slow runs lose their time. A large part was rediscovery. A one-line change to a `font-weight` took 280 seconds on a project that already had dozens of runs behind it. Around 160 of those seconds went to a subagent finding out where the styles live and how the project is built, facts that earlier runs already knew.

[opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"}, the agent behind the AI action, only knows static [rules files](https://opencode.ai/docs/rules/){rel="&#x22;nofollow&#x22;"} like an `AGENTS.md` in the repository. A human writes that file by hand, the agent does not add anything to it. There are community plugins for learned memory, but they do not fit Knecht.

- Everything a plugin writes to disk lands in the throwaway checkout of the run and is gone afterwards. Knecht would have to build the persistence outside the run anyway.
- The best-known plugin, [opencode-mem](https://github.com/tickernelz/opencode-mem){rel="&#x22;nofollow&#x22;"}, only saves its memories when the session has been quiet for a while. That is the pause in which a human in a chat is not typing. But Knecht starts opencode [non-interactively](https://opencode.ai/docs/cli/){rel="&#x22;nofollow&#x22;"}, and that process exits right after its answer. The pause never comes, so the plugin would never save.

So we built this directly into Knecht, as a small store per project on the host, outside every sandbox.

## An index and topic files

The memory consists of an index file `MEMORY.md` and any number of topic files. After a few runs on a [Craft](https://craftcms.com){rel="&#x22;nofollow&#x22;"} project it can look like this:

::code-tree{default-value="MEMORY.md"}
```md [MEMORY.md]
- Styles: Tailwind, tokens, build step, see styles.md
- Build and tests: commands and pitfalls, see build.md
```

```md [styles.md]
Tailwind 4, tokens live in src/css/config.css.
Font sizes and weights only via text-* utilities, no raw values.
After CSS changes run `ddev npm run build`,
templates load the built file from web/dist/.
```

```md [build.md]
Build: `ddev npm run build`
Tests: `ddev php vendor/bin/phpunit`
The build needs DDEV running, plain npm on the host
fails on the node version.
```
::

The index holds one line per topic and is merged into the instructions on every agent call, so it is always in context. To keep that cheap, it has a hard limit of 2 KB. The agent only reads a topic file when the index points at something relevant. Until then the topic files cost no context. The pattern comes from Claude Code, whose [auto-memory](https://code.claude.com/docs/en/memory){rel="&#x22;nofollow&#x22;"} is built the same way.

The agent maintains the memory itself, following rules in the `AGENTS.md` that Knecht puts into every sandbox. It should rewrite notes instead of appending, delete outdated notes, and record corrections that come in through the follow-up chat on the run page. If you write "no, we do not use utility classes" there once, you should not have to write it a second time. And the agent should briefly check its own notes before building on them, because the project can have changed since the last run.

## Copy instead of mount

Before every agent call Knecht copies the notes into the checkout of the run. After the call it copies them back to the host. The copy back also happens for failed steps, because the notes hold facts about the project, not a run status.

A mount into the sandbox would have been simpler. But with the copy, every run works only on its own state, and Knecht has one place during the copy back where it can check what the agent wrote.

- Only plain Markdown files at the top level are accepted, no [symlinks](https://man7.org/linux/man-pages/man7/symlink.7.html){rel="&#x22;nofollow&#x22;"}, no subfolders, no hidden files.
- The index may be at most 2 KB, all files together at most 64 KB. If the copy is larger, Knecht does not accept it at all. The last valid state stays, and one line about it appears in the run log.

Knecht discards oversized copies instead of trimming them, because the agent would not notice a trim and would then keep working with incomplete notes. With the old state it can clean up itself in the next run. The rules for that are in the `AGENTS.md`. Knecht still checks the limits itself, so the context does not grow when the model ignores the rules.

## What is still missing

There is no view in the project settings yet that shows what Knecht has remembered. You would want to read the notes there and also correct them. It is also open whether Knecht should at some point summarize an oversized copy instead of discarding it. That is only worth building if discards turn out to be frequent in practice.


# Beta Testers Wanted

Knecht runs. What it needs now are real projects, because local tests do not produce real bugs. So we search for a handful of agencies and freelancers that use Knecht first in their daily work. If you want to join right away, sign up in the [form below this post](https://knecht.works/#cta).

## What you get

The start should cost you nothing. So this is what you get from us:

- You do not have to install Knecht yourself. We host your instance during the beta and take care of updates and operations.
- 100 € of OpenCode credit, so that the AI agents can start right away.
- The first year after the release is free for you.
- Your logo with a link on the home page.

So you take no financial risk, and you start with a functional Knecht, configured for your projects. If you prefer to run Knecht on your own server, you can still do that.

## What we need

In return, we want one person who really uses Knecht and tells us regularly where it blocks them, what is missing, and what works well. We do not ask for more. This feedback from real projects is worth more to us than any local test.

## Who is a good fit

Knecht helps most where many projects need maintenance. You are a good fit if you work with DDEV and maintain enough projects that security updates and bug fixes are routine work for you. If your projects do not run on DDEV yet, but you can convert them with little effort, that also works.

## Take part

If this sounds like you, sign up in the [form below this post](https://knecht.works/#cta) and select "I want to test actively and give feedback". We will then contact you. If you have questions first, send a mail to <hallo@knecht.works>.

And if testing is not your thing, but you want to follow the progress, select "Get updates only" in the [form](https://knecht.works/#cta).


# From a Shared Docker Daemon to One Sandbox per Run

::note
This post is a look under the hood. The container architecture is the base that makes parallel previews with DDEV projects possible. It is not the product itself. The [home page](https://knecht.works) and [What Knecht does](https://knecht.works/updates/was-macht-knecht) explain what Knecht does and who it is for.

Update, July 2026: We built the Sysbox sandbox, and it worked. Still, we removed it again. The follow-up post [Back to the shared daemon](https://knecht.works/updates/sandbox-rollback) explains why. The path to the decision below is still worth a read, because the follow-up post builds on it.
::

Knecht itself runs as a Docker container, but it must boot DDEV projects, which also consist of containers. The most risky assumption in the full architecture was that this works at all. Thus we tested this assumption first, before we wrote the real code.

## The approach

Some background first. Docker consists of two parts. The [Docker daemon](https://docs.docker.com/get-started/docker-overview/#docker-architecture){rel="&#x22;nofollow&#x22;"} is the service that really creates and manages containers. The Docker CLI is only a client that talks to the daemon through a Unix socket (`/var/run/docker.sock`). If you have the socket, you control the daemon.

Knecht uses exactly this. The container does not start its own daemon. It mounts the socket of the host and thus controls the host daemon. This pattern is called [Docker-out-of-Docker](https://www.avonture.be/blog/docker-out-of-docker-dood/){rel="&#x22;nofollow&#x22;"} (DooD). The DDEV containers then run as siblings next to the Knecht container on the host, not nested inside it. [Coolify](https://coolify.io){rel="&#x22;nofollow&#x22;"} and many CI runners work in the same way.

## The test

::steps{level="3"}
### The host daemon is reachable

`docker ps` in the container shows the host containers. The socket mount works.

### A DDEV project boots

We put a minimal PHP project at a fixed path and ran `ddev start`. DDEV started the web server and the database on the host.

### Containers are host siblings

On the host, the project containers appear as normal neighbors of the Knecht container.

### The app is reachable

The booted project responds. One detail is important here. `*.ddev.site` always resolves through DNS to `127.0.0.1`, which is the container itself. Thus the preview proxy must contact the web container directly through the Docker network.
::

This proves the base. A process in the Knecht container can boot real DDEV stacks, with the source code correctly mounted.

## Two problems remained

But the test also showed the limits of the approach.

### No isolation between runs

Everything runs on one shared daemon. But Knecht must run many previews in parallel, without conflicts between runs. We even had to remove the [DDEV router](https://docs.ddev.com/en/stable/users/usage/architecture/){rel="&#x22;nofollow&#x22;"}. The router is the reverse proxy that DDEV puts in front of all projects and that binds ports 80 and 443 on the host. Fixed host ports exist only one time, and many parallel projects then collide. Without the router, Knecht must change the `.ddev/config.yaml` and, for example, overwrite the URLs.

### Foreign code at the host socket

The agent executes code, and we do not fully control what it does. An attacker can hijack an agent through [prompt injection](https://simonwillison.net/series/prompt-injection/){rel="&#x22;nofollow&#x22;"}, for example with manipulated content in the repo or in a data source. Then the agent no longer does what we want. An attacker who reaches the host socket at this point controls the daemon. And who controls the daemon can start any container with any mount. In effect, this is root on the server.

## The solution: one sandbox per run

Both problems have the same answer. Each run gets its own Docker daemon in its own sandbox. With this, the reason to remove the router also disappears. Port 80 in sandbox A cannot collide with sandbox B, because each sandbox has its own network namespace. Thus projects run again with all their URLs and settings.

The open question is what the sandbox is. We examined the usual candidates.

### Privileged Docker-in-Docker

This is a second daemon in a container with [`--privileged`](https://docs.docker.com/engine/containers/run/#runtime-privilege-and-linux-capabilities){rel="&#x22;nofollow&#x22;"}. The flag turns off almost all protection mechanisms and gives the container access to the host devices. A malicious dependency then reaches the host without an exploit. Not an option.

### Kata Containers

[Kata](https://katacontainers.io){rel="&#x22;nofollow&#x22;"} starts each container in a lightweight VM with its own kernel. This is the strongest boundary and the approach behind [Firecracker](https://firecracker-microvm.github.io){rel="&#x22;nofollow&#x22;"}, on which, for example, AWS Lambda runs. But Kata needs `/dev/kvm`, and normal cloud VPS providers offer [no nested virtualization](https://lowendtalk.com/discussion/154261/searching-vps-for-nested-virtualization){rel="&#x22;nofollow&#x22;"}. This would force bare metal and conflicts with the goal to install Knecht on a normal VPS. Not an option.

### gVisor

[gVisor](https://gvisor.dev){rel="&#x22;nofollow&#x22;"} intercepts syscalls in a userspace kernel and needs no KVM. It isolates application processes well, but it has problems as a Docker host itself. [It supports iptables only in part](https://github.com/google/gvisor/issues/9917){rel="&#x22;nofollow&#x22;"}, and [overlayfs breaks with Docker v29](https://github.com/google/gvisor/issues/12475){rel="&#x22;nofollow&#x22;"}. But a Docker host is exactly what DDEV needs. Not an option.

### Our choice: Sysbox

[Sysbox](https://github.com/nestybox/sysbox){rel="&#x22;nofollow&#x22;"} is a container runtime that permits Docker-in-Docker without `--privileged`. For this, it uses [user namespaces](https://man7.org/linux/man-pages/man7/user_namespaces.7.html){rel="&#x22;nofollow&#x22;"}. Root in the container is mapped to an unprivileged user on the host. Sysbox was built exactly for this case, needs no KVM, and thus runs on every normal Linux server.

## The threat model decides

In the end, the decision does not come from the runtime but from the threat model. The threat model asks who attacks and what the attacker can reach. Knecht is [single-tenant](https://www.geeksforgeeks.org/system-design/single-tenant-vs-multi-tenant-architecture/){rel="&#x22;nofollow&#x22;"}, one agency, its projects, its server. The VM boundary of Kata mostly protects against a customer who breaks out of one environment into the environment of another customer. This case does not exist here.

## What comes next

Next, we build the Sysbox sandbox per run (own daemon, DDEV with router) and a central ingress with an auth gate that routes preview URLs into the correct sandbox. The next milestone is DDEV with the router in a Sysbox sandbox on a real Linux host, reachable from the ingress.

Perhaps there will also be a first showcase of the prototype.


# The Docs Are Online

Until now these updates were all there was about Knecht. They tell why something is built the way it is, but not how to set it up. Anyone who wanted to install an instance or build a workflow had to piece the steps together from several posts. Since this week there is documentation at [knecht.works/docs](https://knecht.works/docs). This post shows what is in it and what the pages can do beyond text.

## What Is in It

The docs are in English, like the dashboard, so the terms are the same on both sides. They consist of three parts.

::card-group
  :::card
  ---
  icon: i-lucide-rocket
  title: Get Started
  to: https://knecht.works/docs/get-started/introduction
  ---
  What Knecht is, the terms from the dashboard, installation, setup, and day-to-day operation.
  :::

  :::card
  ---
  icon: i-lucide-workflow
  title: Usage
  to: https://knecht.works/docs/usage/projects
  ---
  Projects, workflows, triggers, and the AI agent, the things you work with every day.
  :::

  :::card
  ---
  icon: i-lucide-life-buoy
  title: Resources
  to: https://knecht.works/docs/resources/beta-testers
  ---
  The page for beta testers and a troubleshooting section per framework.
  :::
::

Much of it is not very detailed yet. The docs grow step by step with the product. Knecht itself still has some rough edges, and we polish those first before we document them in detail. Otherwise we would have to rewrite the pages shortly after.

## Features

### Search

At the top right there is a search, which also opens with :kbd{value="meta"} :kbd{value="K"}. It searches all docs pages down to the section level, so a hit jumps straight to the matching heading.

![The docs search above the "Introduction" page, with the results grouped by Get Started, Usage, and Resources](https://knecht.works/assets/docs-search.png)

### Ask Knecht

Next to the search there is the button "Ask Knecht", which also answers to :kbd{value="meta"} :kbd{value="I"}. It opens a chat window where you ask questions in full sentences, in German or English. The assistant answers from the content of the website, that is the docs and these updates, and links the page where the answer is. What is not on the website, it does not know, and it says so.

![The "Ask Knecht" panel next to the docs, with a question about the installation and an answer listing the requirements and the install command](https://knecht.works/assets/docs-ai.png)

If you open the window on a docs page, the assistant gets that page as context and prefers it when answering. This can be switched off in the window. Behind it runs a Claude model that receives the complete content of the website with every question. Knecht does not store the chats.

### Docs as Markdown

Every docs page is also available as plain Markdown. The button "Copy page" at the top of the page copies the text to the clipboard. The menu next to it offers the Markdown link, the raw view, and the option to open the page directly in ChatGPT or Claude. If you set up Knecht with a coding agent, this is how you hand it the right page, without HTML around it.

::tip
For everything at once there is [llms.txt](https://knecht.works/llms.txt) with the overview and [llms-full.txt](https://knecht.works/llms-full.txt) with the complete content of the website in one file.
::

### Feedback per Page

On every docs page you can tell us directly whether it helped and what is missing.

- At the end of every page there is the question "Was this page helpful?" with thumbs up and thumbs down. One click is enough, we see per page how often each answer came in.
- "Provide Feedback" opens a GitHub issue in the [website repo](https://github.com/knecht-works/knecht-www){rel="&#x22;nofollow&#x22;"}, with the page title already in the subject. The repo is public, so a typo can also be fixed directly as a pull request.

### Shortcuts

Search and "Ask Knecht" can be used entirely from the keyboard.

| Shortcut                           | Action                                       |
| ---------------------------------- | -------------------------------------------- |
| :kbd{value="meta"} :kbd{value="K"} | Open the search                              |
| :kbd{value="meta"} :kbd{value="I"} | Open and close "Ask Knecht"                  |
| :kbd{value="meta"} :kbd{value="O"} | Start a new chat                             |
| :kbd{value="tab"}                  | Switch the current page as context on or off |

## Rough Edges

The docs are new, and we wrote them as the people who know Knecht best. What is obvious to us may be missing for exactly those who set it up for the first time. That is why we are most interested in where you got stuck. Which page left a question open, which term is unexplained, which setup did not work as described. Small hints are often the most useful ones.

## Discord

For everything that is not an issue, there is now a Discord server. There we answer questions about the setup, discuss workflow ideas, and show what we are building right now. If you try Knecht or plan to, you are welcome there, even without a specific question.

::callout
---
color: primary
icon: i-simple-icons-discord
target: _blank
to: https://discord.gg/WuxjmtgUyX
---
Join the Knecht Discord
::


# GitHub Auth Evolution

The GitHub login worked from day one. Still, we rebuilt it three times.

The reason is that "connect with GitHub" hides three separate questions, and people often mix them. Who sits in front of the dashboard? With what does the server clone repos and open PRs? And who is permitted to use this instance at all? At the start, we answered all three with a single token. This post shows the path from there to the current state, together with the GitHub quirks that we found on the way.

## What an OAuth App is

An OAuth App is the classic "Sign in with GitHub" button. The app sends the user to GitHub. The user confirms the access there and comes back with an access token. The [scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps){rel="&#x22;nofollow&#x22;"} that the app requests define what this token can do. `read:user` means that the app can only read the profile. `repo` means full read and write access to **all** repos that the user can reach.

And exactly there our problem started.

## Stage 1: one token for everything

The first version of Knecht was an OAuth App with the `repo` scope. The token that confirmed the login was also the credential for all Git operations. There was no second secret and no setup. This was practical, but wrong in two ways:

- **The scope is too wide.** A `repo` token can do everything that the user can do, in each of the user's repos, not only in the projects that Knecht maintains. OAuth scopes cannot be more precise than this.
- **The credential belongs to one person.** If the user rotates the token or leaves the agency, the server loses access to all repos. Server infrastructure that depends on the account of one employee is a time bomb.

## What a GitHub App does differently

For stage 2, we moved the repo access to a **GitHub App**. The [difference to an OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps){rel="&#x22;nofollow&#x22;"} is fundamental:

- A GitHub App is a **separate actor** with its own identity, not a user who lends personal permissions.
- You **install** it on selected repos. The access is limited to exactly these repos.
- It authenticates with its **private key** and creates [installation tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app){rel="&#x22;nofollow&#x22;"} from it. Each token is valid for about one hour and scoped to the installed repos. When one token expires, the app simply creates the next one.

The login stayed OAuth, but with a smaller scope, `read:user`. Knecht uses the token one time to load the profile and then discards it. It never stores the token. With this, identity and repo access were cleanly separated.

But the setup was painful. The operator had to create an OAuth App **and** a GitHub App by hand, copy four secrets into the `.env`, encode the private key as base64, and enter callback URLs. All this before anything worked.

## Stage 3: the Manifest Flow

Then we noticed that a GitHub App already contains its own OAuth client. Thus a single app can do both, login and repo access. The separate OAuth App was unnecessary.

And for exactly this case, GitHub has the [App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest){rel="&#x22;nofollow&#x22;"}. A program describes the desired app as JSON (name, callback URLs, permissions) and sends it to GitHub. GitHub creates the app and returns **all** credentials.

In Knecht, this works as follows. At the first start, the dashboard shows a button. One click, GitHub creates the app, and Knecht stores the credentials encrypted in its own database. The cipher is AES-256-GCM, and [HKDF](https://datatracker.ietf.org/doc/html/rfc5869){rel="&#x22;nofollow&#x22;"} derives the key from the session password, which must be set in any case. Thus the encryption costs no new env variable.

Exactly two things remain for the operator to supply: the session password and the base URL.

There is one trade-off. If you rotate the session password, the stored credentials become unreadable. The solution then is not to decrypt them but to run through the setup one more time.

## Stage 4: who gets access

One hole stayed open until the end. The login checked **identity** but not **permission**. Each GitHub account that completed the OAuth flow got a session.

Whether an attacker can use this depends on a GitHub quirk that you must understand one time. An app is either [private or public](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private){rel="&#x22;nofollow&#x22;"}:

- A **private** GitHub App shows the authorize page only to its owner (or to members of the owner org). All others see a 404. This looks like built-in access control, but it makes it impossible to invite external team members. They do not even reach the consent page.
- A **public** app lets each GitHub user through the identity flow. Only this makes it possible to onboard any team member. But then GitHub gates nothing at all.

::callout{color="primary" icon="i-lucide-lightbulb"}
The visibility of a GitHub App is not access control. Private locks out the wrong people, and public lets everybody in. If you want to decide who can log in, you must do it yourself.
::

Thus the app of Knecht is public, and Knecht itself holds the permission with an **allowlist**. This is a simple members table with GitHub logins. During the setup, Knecht automatically adds the creator as the owner. You invite all other members through the settings. After the GitHub login, Knecht rejects each person who is not on the list.

"Public" only means that strangers could install the app on their own repos. This is harmless, because Knecht only uses installations that it knows.

One more detail, because people often miss it. A session is typically a cookie that stays valid until it expires. If you check only at login, removed members stay in the system for days. [OWASP calls this a lack of server-side invalidation](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html){rel="&#x22;nofollow&#x22;"}. Thus Knecht checks the membership again at **each** request. When someone is removed, that person is out at the next click.

## What is still open

Roles. At the moment, each member has full access, and this includes invitations. For the small teams that Knecht is built for now, this is enough. Finer permissions will come when teams need real roles.


# One Interface for All Integrations

::note
This post is a look under the hood. It explains how the integrations are built in the server, not what you do with them. What Knecht does is on the [home page](https://knecht.works), and how it works on GitHub and in Jira is in [Knecht Now Replies on GitHub](https://knecht.works/updates/sessions-and-mentions). Setup is covered in the docs for [GitHub](https://knecht.works/docs/integrations/github) and [Jira](https://knecht.works/docs/integrations/jira).
::

Knecht started with one integration, GitHub. Then Jira came along, and Jira works differently. There are tickets instead of pull requests and [status categories](https://support.atlassian.com/jira-cloud-administration/docs/what-are-issue-statuses-priorities-and-resolutions/){rel="&#x22;nofollow&#x22;"} instead of open and closed. A ticket cannot show a pull request, so Knecht writes the result back as a comment. So Jira got its own code. Every further issue tracker would have gotten that code once more. This post tells how we turned it into one shared interface.

This is what the result looks like in Jira. A ticket gets a label, Knecht picks it up, works in its environment and comes back with a pull request and a comment.

:update-youtube{#9FFm1AlmRn4 caption="A Jira ticket gets a label, Knecht works and comes back with a PR and a comment" title="Knecht Works on Jira"}

## The Problem

### Copied Infrastructure

Every tool needs the same four things. Knecht has to store credentials, show the connection in the settings, load labels and statuses for the trigger form and receive webhooks. A [webhook](https://docs.github.com/en/webhooks/about-webhooks){rel="&#x22;nofollow&#x22;"} is the HTTP request a tool sends to tell Knecht about a change. Jira had its own API routes, its own database table and its own settings panel for this. A second tracker would have copied all of it and only swapped field names and texts.

### Tool Names in the Code

The bigger issue was that the rest of Knecht knew the tools by name. Wherever an integration mattered, there was a check like this:

```ts
if (tool === 'jira') {
  await postResultComment(ticket)
}
```

The code that finishes a run knew that Jira needs a result comment. Mention handling only knew GitHub. For every new tool we would have had to find and extend all of those places.

## The Interface

### Capabilities, Not Names

Now an integration is one object that fulfils a fixed [TypeScript interface](https://www.typescriptlang.org/docs/handbook/2/objects.html){rel="&#x22;nofollow&#x22;"}. The rest of Knecht no longer asks which tool it is looking at, but what the tool can do. If you know your design patterns, this is an [adapter](https://refactoring.guru/design-patterns/adapter){rel="&#x22;nofollow&#x22;"}. Heavily simplified, the interface looks like this:

```ts
interface Integration {
  webhook: {
    verify(request): boolean
    parse(request): Delivery
  }
  comment(ticket, text): Promise<void>
  labels?: { list(ticket), apply(ticket, names) }
  statuses?: { list(ticket), move(ticket, status) }
  assignee?: { take(ticket), handBack(ticket, person) }
}
```

`verify` checks the [signature](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries){rel="&#x22;nofollow&#x22;"} of a webhook, that is whether it really comes from the tool. `parse` translates it into a shape Knecht understands. Every tool can comment, everything with a question mark is [optional](https://www.typescriptlang.org/docs/handbook/2/objects.html#optional-properties){rel="&#x22;nofollow&#x22;"}. The check from above becomes:

```ts
if (integration.labels) {
  await integration.labels.apply(ticket, ['bug'])
}
```

### One Path for Every Webhook

`parse` returns the same shape for every tool. A webhook can contain a comment that addresses Knecht directly (a [mention](https://knecht.works/updates/sessions-and-mentions)), a status change on the ticket, or an event a [trigger](https://knecht.works/docs/usage/triggers) reacts to. A trigger is the rule that starts a workflow. Often a webhook carries several of these, a closed ticket for example is a status change and maybe a trigger event too. What Knecht does with them lives in exactly one place:

```ts
const delivery = await integration.webhook.parse(request)

if (delivery.comment) handleMention(delivery.comment)
if (delivery.statusChange) syncTicketStatus(delivery.statusChange)
if (delivery.event) startMatchingWorkflows(delivery.event)
```

The integration only has to know how its tool sends data. What follows from it, Knecht decides the same way for every tool. Alexis King describes the idea behind this in [Parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/){rel="&#x22;nofollow&#x22;"}: foreign data is translated into your own type once at the boundary, and after that the code only works with that type.

## Differences as Data

What still differs between two tools is mostly terms and formats. A ticket has another name, other statuses count as done, the title sits somewhere else in the payload. Each integration describes that as data, and the logic around it exists only once.

### The Tracker

A tracker is a tool where a team manages its tickets, like Jira. What Knecht needs to know about it fits into a short description:

```ts
const jira = {
  noun: 'ticket',
  statusGroups: { new: 'To Do', indeterminate: 'In Progress', done: 'Done' },
  closedGroups: ['done'],

  toTicket: issue => ({
    title: issue.fields.summary,
    body: adfToMarkdown(issue.fields.description),
    status: issue.fields.status.name,
    labels: issue.fields.labels,
  }),
}
```

The upper part is the tool's vocabulary, that is what a ticket is called, which status categories exist and which of them count as done. `toTicket` translates the webhook data into one uniform ticket. From there the same code decides for every tracker whether a trigger starts, and the text the [agent](https://knecht.works/docs/usage/agent) reads about the ticket comes from it too.

### The Trigger Form

In the [trigger dialog](https://knecht.works/docs/usage/triggers) you pick which event starts a workflow. Each integration describes the events it offers:

```ts
trigger: {
  form: {
    events: [
      { label: 'Label added', options: 'labels' },
      { label: 'Status reached', options: 'statuses' },
    ],
  },
  options: {
    labels: () => jira.get('/label'),
    statuses: () => jira.get('/status'),
  },
}
```

From `form` Knecht builds the dialog. `options` fills the dropdowns with the labels and statuses that actually exist in Jira. `form` is plain data and goes to the browser, `options` runs on the server, because only the server has the credentials.

### The Connection

The connection is the set of credentials Knecht uses to read and write in the tool, for Jira the site URL, an email and an API token. An admin enters them once in the settings, and from then on the connection applies to the whole instance. This form is a description too. The integration only says which fields it needs and how it checks that the credentials work:

```ts
connection: {
  fields: [
    { key: 'siteUrl', label: 'Site URL', type: 'url' },
    { key: 'email', label: 'Email', type: 'email' },
    { key: 'apiToken', label: 'API token', type: 'secret' },
  ],
  verify: values => jira.whoAmI(values),
}
```

One shared Vue component builds the form from it, and one shared API route saves it. The field type brings its rules. A `url` has to start with https, and a `secret` is [stored encrypted](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html){rel="&#x22;nofollow&#x22;"} and only shown as a preview. Before saving, `verify` signs in to the tool once, so wrong credentials never get stored.

## Tests Against the Interface

### From Clicking to Fixtures

At first we tested triggers by hand. The local Knecht instance was reachable through a [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/){rel="&#x22;nofollow&#x22;"}, we created a ticket in Jira, set a label, moved the status and checked the log to see whether the right workflow started. That took a while, and after every change to the trigger logic it started over.

So Knecht can now write every verified webhook to a folder as a JSON file. One round of clicking through the tool is enough, and the recorded webhooks become fixtures. As of September 2026 there are 89 of them. The tests replay them and state for each trigger which webhooks it has to fire on and which it must not:

```ts
const cases = [
  { trigger: 'Label "bug" added', firesOn: ['ticket-labeled-bug'] },
  { trigger: 'Status "Done" reached', firesOn: ['ticket-moved-to-done'] },
]

for (const { trigger, firesOn } of cases) {
  for (const webhook of recordedWebhooks) {
    expect(fires(trigger, webhook)).toBe(firesOn.includes(webhook.name))
  }
}
```

Once the connection to a tool works and one round of webhooks is recorded, we know within seconds after every change whether the triggers still hold, without opening the tool. If a tool changes its format, we record again and the tests show right away what changed.

### One Suite for All

The fixtures check whether triggers decide correctly. Whether an integration fulfils the interface at all is checked on a second level. Because all integrations share the same interface, they run through the same test suite in [Vitest](https://vitest.dev/guide/){rel="&#x22;nofollow&#x22;"}. An integration only provides building blocks that create webhooks in its format:

```ts
webhookSuite({
  integration: jira,
  created: project => jiraWebhook('issue_created', project),
  labeled: project => jiraWebhook('issue_updated', project, { labels: ['bug'] }),
  mention: project => jiraComment(project, '@Knecht please take a look'),
})
```

The suite sends these webhooks through the real route and expects the same behaviour from every integration.

Martin Fowler calls this a [contract test](https://martinfowler.com/bliki/ContractTest.html){rel="&#x22;nofollow&#x22;"}. For a new integration it means we do not have to think about what to test. As soon as it provides the building blocks and the suite is green, it behaves like the others.

## What We Take Away

A new integration now consists of the tracker description, the API calls and the connection form. Triggers, mentions, comments, labels, statuses and the settings panel come with the interface. If you build something like this yourself, four points can guide you:

- The rest of the app asks for capabilities, never for the name of the tool.
- Incoming data is translated into one shared shape at the boundary. After that there is no tool-specific code. Microsoft describes this pattern as an [anti-corruption layer](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer){rel="&#x22;nofollow&#x22;"}.
- What only differs in data, like forms or terms, is described as data and not as code.
- Tests run against the interface, so every integration has to pass the same tests.


# The Landing Page Is Online

The landing page is online. We made this decision on purpose, before the prototype even exists.

::callout{color="primary" icon="i-lucide-mouse"}
Click the Knecht.
::

## Why this page

It is a risk to build a full product first and then hope that somebody needs it. Thus the landing page comes first. The page does three things:

- It explains the idea in a few sentences.
- It collects the first beta testers.
- It makes the path public, so that feedback comes early and not only at launch.

### Language

Many startups aim at the international market from the start. We think that this starts with the language. We will focus on the DACH region first. Thus English as a second language must wait a little longer.

## What the page is not (yet)

We want to prevent false expectations. This page is not a product. It has no login, no demo, and nothing that you can try. You see the idea and a first look at the planned interface.

## What comes next

The prototype comes next, with projects, workflows, and the AI agent.

The goal for the next weeks is clear. We want to find the first 3 to 5 agencies as beta testers. They test Knecht on real projects and give honest feedback about what works.

::callout{color="neutral" icon="i-lucide-arrow-right"}
Sign up as a [beta tester](https://knecht.works/#cta) if you want to join early.
::


# Langdock as an AI Provider

The agent in the [AI action](https://knecht.works/updates/workflow-engine) is [opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"}. Until now it ran through the providers of OpenCode itself, Zen or Go, with a key from the OpenCode console. Now we have added Langdock as a provider, a European alternative. Here too, one API key covers the models of several vendors, but every request of the agent stays in the selected region.

## What Langdock is

[Langdock](https://langdock.com){rel="&#x22;nofollow&#x22;"} is an AI gateway for European companies. It sits in front of several model vendors, among them OpenAI, Anthropic, Google, Meta, and Mistral. The team signs one contract and gets one API key. Behind that key, the models of all vendors are available.

The second reason for such a gateway is data residency. That is the guarantee that every request is processed in a fixed region, EU or US. This affects the agent directly, because its prompts contain code and data from the client project. Many client contracts require that such data does not leave the EU. With Langdock in the EU region, this also holds for the work of the agent. Often that is the condition under which the agent may work on the project at all.

## Opencode does not know Langdock

opencode resolves providers through the [models.dev](https://models.dev){rel="&#x22;nofollow&#x22;"} registry. For the previous providers, an environment variable with the API key is enough. opencode knows the rest itself. Langdock is not in that registry, so this path does not work.

Instead, Knecht generates an `opencode.json` in the checkout for every run. In that file, it declares Langdock as a custom provider, with the endpoint of the selected region and exactly the models this run may use. Shortened, the block looks like this:

```json
{
  "provider": {
    "langdock": {
      "name": "Langdock",
      "options": {
        "baseURL": "https://api.langdock.com/openai/eu/v1",
        "apiKey": "{env:LANGDOCK_API_KEY}"
      },
      "models": { "gpt-5.5": {} }
    }
  }
}
```

The key itself is not in the file. The config only points to an environment variable with `{env:LANGDOCK_API_KEY}`, and Knecht hands the value directly to the opencode process. So the key never lands in the checkout where the agent works.

One quirk of the gateway hides in the `baseURL`. Langdock speaks a different API depending on the model. Claude models use the Anthropic-compatible one, all other models the OpenAI-compatible one. Knecht decides by the model name under which endpoint a model is declared in the config. In the picker, you just select a model. You never notice the split.

## The setup

Everything lives under "Settings" → "Agent". There you select Langdock as the provider, and the region select appears next to it. The region applies to the whole instance, that is, to every request from every run. Then you save the Langdock API key. Like all provider keys, it is stored [encrypted](https://knecht.works/updates/gh-auth-evolution) in the database. Afterwards it can only be replaced, not read again.

![The agent settings with Langdock as the provider, the region select, and the open model picker](https://knecht.works/assets/settings-agent-langdock.png)

Once the key is saved, the model picker loads the list live from the Langdock workspace. It shows exactly the models that are enabled there, GPT and Claude models in the same picker. The default model and the optional subtask model, a smaller model for side tasks of the agent, work like with every other provider.

::note
When you switch the provider, Knecht clears the stored models, because the old names would not resolve in the catalog of the new provider. The AI action only runs again after a new default model is selected.
::

## Mixing models

Nothing changes in the AI action itself. The agent works in the running project as usual. It reads code, changes files, and executes commands, also with reasoning models like GPT-5.5. And because one key covers all models of the workspace, a workflow can still mix vendors through the per-step model override:

```yaml
steps:
  - type: ai
    id: analyze
    label: Analyze bug
    model: gpt-5.5
    prompt: Stelle den Bug aus {{ inputs.title }} nach und beschreibe die Ursache.
  - type: ai
    id: fix
    label: Fix bug
    model: claude-sonnet-4-5
    prompt: Behebe die Ursache aus {{ steps.analyze.text }}.
```

Both steps run through the same Langdock key and in the same region. The move to the EU gateway takes nothing away that you know from OpenCode Zen.


# Why Knecht Is Not Open Source

The [Knecht repo](https://github.com/knecht-works/knecht-cloud){rel="&#x22;nofollow&#x22;"} was public on GitHub from the start, but it had no license. We changed that now. Knecht is under the Functional Source License, short FSL. This post explains why a license was necessary, why we did not select MIT, and what you can officially do with the code.

## Without a license, nothing is permitted

Public and free to use are two different things. Code has copyright protection, like a text or a photo. Without an explicit license, the default rule of copyright law applies. All rights are reserved. [GitHub states this itself](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository){rel="&#x22;nofollow&#x22;"}. You can only view a public repo without a license and fork it on the platform. You cannot download the code, change it, or use it in production.

A repo without a license is therefore more restrictive than the strictest license. That was not our intention. We simply did not decide the license question yet. Beta users who host Knecht themselves had our permission, but only in spoken form, not in writing.

## The dilemma

We had two requirements for the license, and at first sight they conflict. The code must stay public, and everyone must be able to host, read, and change Knecht for free. At the same time, Knecht must be able to make money one day, so the project can operate permanently. How exactly is open. Maybe a hosted version, maybe paid extra functions for teams.

A permissive license like [MIT](https://opensource.org/license/mit){rel="&#x22;nofollow&#x22;"} or Apache does not fit these goals. Permissive means that everyone can do everything. A company could take Knecht and sell it as its own product. Elasticsearch showed where this leads. It had the Apache license, AWS sold it as its own managed service, and Elastic got nothing. In 2021 [Elastic moved to a more restrictive license](https://www.elastic.co/blog/licensing-change){rel="&#x22;nofollow&#x22;"}. AWS forked the last free version and now operates it as [OpenSearch](https://opensearch.org/){rel="&#x22;nofollow&#x22;"}. Terraform (fork: [OpenTofu](https://opentofu.org/){rel="&#x22;nofollow&#x22;"}) and Redis (fork: [Valkey](https://valkey.io/){rel="&#x22;nofollow&#x22;"}) went through the same cycle.

These stories share one point. The license change came late, after a community grew on the free license. A license change only applies to new versions. Code that was published under a permissive license stays permissive forever. And after the change, the community understandably supports the fork. If a limit is necessary, it must exist from the start.

## The candidates

We examined five licenses closely:

| License      | Model                   | Forbids                                        | Becomes open source    |
| ------------ | ----------------------- | ---------------------------------------------- | ---------------------- |
| MIT / Apache | open source, permissive | nothing                                        | it already is          |
| AGPL         | open source, copyleft   | nothing, but you must publish your own changes | it already is          |
| BSL          | source available        | what the vendor defines                        | after up to four years |
| ELv2         | source available        | operation as a managed service                 | never                  |
| FSL          | source available        | competitive products                           | after two years        |

The [AGPL](https://www.gnu.org/licenses/agpl-3.0.html){rel="&#x22;nofollow&#x22;"} is the one true open source license that protects a business model. If you operate AGPL software as a web service or build it into a product, you must publish your own code. This blocks competitors reliably. But it also blocks the wrong people. Many companies ban AGPL software completely, because their legal team does not want to examine the publication duty in each case. Agencies with careful customers would be affected most, and Knecht is made exactly for these people.

BSL, ELv2, and FSL use the same model, and the model is called source available. The code is public and free to use, but only the vendor can sell it. The [BSL](https://mariadb.com/bsl11/){rel="&#x22;nofollow&#x22;"} (from MariaDB) requires that the vendor writes the permitted use himself. Therefore each BSL text is different, and you must examine each one. Even the question if you can host the software for free depends on the vendor. The [ELv2](https://www.elastic.co/licensing/elastic-license){rel="&#x22;nofollow&#x22;"} (from Elastic) is simple, but it never becomes open source. The FSL ([from Sentry](https://blog.sentry.io/introducing-the-functional-source-license-freedom-without-free-riding/){rel="&#x22;nofollow&#x22;"}) is the newest of the three. It is one page of text, it has fixed rules, and it has a built-in conversion to open source.

## What the FSL permits

For most users the license changes nothing. It permits exactly what Knecht users do already:

- host Knecht yourself and use it in production, also commercially, also for customer projects
- read, change, and fork the code
- offer services around Knecht, for example setup and operation for a customer

The license forbids one thing. You cannot offer Knecht to others as your own commercial product. For example, you cannot sell Knecht as a hosted service or distribute Knecht under a different name. The [license text](https://fsl.software/){rel="&#x22;nofollow&#x22;"} calls this Competing Use.

One clause made us select the FSL in the end. Two years after its release, each published version automatically gets the [Apache 2.0 license](https://www.apache.org/licenses/LICENSE-2.0){rel="&#x22;nofollow&#x22;"}, which is true open source. This rule is irrevocable in the license text. We could not cancel it. If Knecht stops one day, the complete code becomes free after two years at the latest. Nobody here builds on software that someone can take away permanently.

## Not open source

People often call every public repo open source. But open source is a defined term. The [definition of the Open Source Initiative](https://opensource.org/osd){rel="&#x22;nofollow&#x22;"} requires that a license does not exclude any field of use, and this includes competition. The FSL does exactly that with its ban on Competing Use. Therefore Knecht is not open source. The correct terms are source available or [Fair Source](https://fair.io/){rel="&#x22;nofollow&#x22;"}. Fair Source is the initiative in which Sentry and others collected this model.

## Next steps

One point is still on the list. Before we merge the first external pull request, we will set up a CLA, a [Contributor License Agreement](https://de.wikipedia.org/wiki/Contributor_License_Agreement){rel="&#x22;nofollow&#x22;"}. It is a short agreement. Contributors give us the right to license their contribution together with the rest of the code. Without it, the rights to the code would spread across many persons. Then we would have to negotiate each later license model with each single contributor.


# From 5 Seconds to Under 0.5

On desktop the landing page loaded immediately. On mobile it was very slow, more than five seconds until it appeared. The cause was a single CSS effect, `blur()`. This post shows the full path from the diagnosis to what really happens under the hood.

## The problem

On mobile the page was simply slow. The load took a long time, and on desktop it was fast. We checked the usual suspects, large images, too much JavaScript, and a slow server. None of them was the cause.

In the end the cause was the background. It contains some large, soft light spots (glows), made with `filter: blur()`. One element was more than 1000px wide, with a blur radius of 100px.

::callout{color="primary" icon="i-lucide-zap-off"}
More than five seconds to the first frame kills a landing page. That moment decides if a visitor stays.
::

## Why blur is expensive

`blur()` is a [convolution](https://developer.chrome.com/blog/animated-blur){rel="&#x22;nofollow&#x22;"}. The browser computes each output pixel from the weighted input pixels around it. The cost scales with the area **and** the radius. A `blur(100px)` is therefore much more expensive than a `blur(5px)`.

This happens for each frame, in about these steps:

::steps{level="3"}
### Render-to-texture

First the browser renders the element into its own off-screen texture. This alone promotes the element to its own compositing layer and costs GPU memory.

### Separable Gaussian

The engine splits a 2D Gaussian into two 1D passes, first horizontal, then vertical. This lowers the cost from O(n²) to O(n) per pixel. This is already the optimized variant.

### Downsampling

For large radii, the engine does not compute at full resolution. Skia (Chrome) [scales down at a sigma above 4](https://api.skia.org/classSkImageFilters.html){rel=""nofollow""}, blurs at the smaller buffer size, and scales up again.
::

Despite all these optimizations, a very large area remains, and it must be ready before the first paint. On desktop you do not notice this. A mobile GPU does this work much more slowly, and exactly this delayed the first frame by seconds.

## Why mobile GPUs suffer most

Almost all mobile GPUs work [tile-based](https://developer.samsung.com/galaxy-gamedev/resources/articles/gpu-framebuffer.html){rel="&#x22;nofollow&#x22;"}. The GPU splits the framebuffer into small tiles and renders them in fast on-chip memory. This saves much memory bandwidth, but it only works while the GPU can compute each tile on its own.

A blur breaks exactly this assumption. The convolution must read pixels beyond the tile border. The GPU cannot keep the effect local to a tile. It must write to the slow system memory and read from it again. On hardware with low fill rate and bandwidth, this is the most expensive case.

## `filter` is not `backdrop-filter`

The header contained a second blur, and that one is a different problem. People often confuse the two:

- **`filter: blur()`** blurs the **own pixels** of the element. The content behind it does not matter.
- **[`backdrop-filter: blur()`](https://www.w3tweaks.com/css/css-filter-backdrop-filter/){rel="&#x22;nofollow&#x22;"}** blurs **everything behind the element**, and it reads those pixels again in each frame.

The second one is brutal when you scroll. The backdrop changes all the time, so the browser computes the blur again and again. [This causes visible stutter](https://github.com/vuejs/vitepress/issues/1049){rel="&#x22;nofollow&#x22;"}, for example in older Firefox builds on Linux. A fixed, semi-transparent header with `backdrop-filter` is one of the most frequent causes of jank.

## Blur and animation

In short, do not animate the radius. Each frame triggers the full convolution on the GPU and breaks the 16ms frame budget. The result is far below 60fps.

Chrome shows a [trick](https://developer.chrome.com/blog/animated-blur){rel="&#x22;nofollow&#x22;"}. You stack some precomputed copies with an exponentially higher blur, and you cross-fade between them with `opacity`. Opacity is compositor-only and therefore cheap. You do not animate the blur, you simulate it.

## The solution

In this case the solution was almost too simple. We removed the blur completely.

The old version blurred a sharp circle, and that was expensive. The glows are now radial gradients with multiple steps, and these gradients are soft by default. The result looks almost identical, but without a filter, without an extra layer, without a convolution. I also removed the `backdrop-filter` in the header.

Other valid options exist, dependent on the case. Deliver a pre-blurred image as an asset, keep the radius small, or apply the blur to a smaller element.

The result is clear. The page now appears in less than half a second instead of more than five seconds. It is ten times faster, and the design looks the same.

## How you find such a problem

In the Chrome DevTools, the [Rendering tab](https://developer.chrome.com/docs/devtools/rendering/performance){rel="&#x22;nofollow&#x22;"} leads quickly to the cause:

- **Paint Flashing** shows in green what the browser paints again. A header that blinks green all the time during scroll is a clear signal.
- **Layer Borders** and the **Layers tab** show which elements get their own compositing layer. Each blur appears there.
- The **Performance panel** shows the long paint tasks and GPU tasks directly in the flame chart.

## The role of older browsers

My first thought was that all browsers support blur. Caniuse confirms this, but support says nothing about performance.

**GPU acceleration can be absent completely.** Firefox renders with WebRender, but on many Linux setups (old Intel GPUs, proprietary Nvidia drivers) it falls back to [software rendering](https://wiki.archlinux.org/title/Firefox/Tweaks){rel="&#x22;nofollow&#x22;"}. Then the blur convolution runs on the CPU, and a smooth effect becomes visible stutter.

::callout{color="primary" icon="i-lucide-lightbulb"}
A green Caniuse bar means that the browser knows the feature. It does not mean that the browser is fast without GPU acceleration.
::

## What I learned

The most beautiful effect has no value when it makes the page slow. Blur is expensive to compute, it creates layers, it has side effects on stacks and positions, and it is fragile on mobile and without GPU acceleration. And always test on real, weak devices, not only on a fast developer machine.


# Every Repo Boots, Even Without a DDEV Config

Until now a repo needed a `.ddev/config.yaml`, or Knecht could not boot it. Since version 0.10 Knecht builds the environment from the files in the repo when there is no config. A dev server becomes the live preview, [hot reload](https://vite.dev/guide/features.html#hot-module-replacement){rel="&#x22;nofollow&#x22;"} included. This post explains what Knecht detects, how the preview gets through, and what we learned about [DDEV](https://ddev.com/){rel="&#x22;nofollow&#x22;"}, [Docker Compose](https://docs.docker.com/compose/){rel="&#x22;nofollow&#x22;"} and [Nuxt](https://nuxt.com/){rel="&#x22;nofollow&#x22;"} along the way.

## What Knecht Detects

At the start of every run Knecht reads the files from the checkout that define the versions anyway:

|                 | Source                                                                | Rule                                                                |
| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------- |
| PHP             | `require.php` in `composer.json`                                      | the highest version of the DDEV image that satisfies the constraint |
| Node            | `mise.toml`, `.mise.toml`, `.tool-versions`, `.nvmrc`, `engines.node` | the first file with a value wins                                    |
| Package manager | the `packageManager` field, else the lockfile                         | npm, pnpm, yarn or bun                                              |

Where nothing is set, the DDEV default applies. The run log names every value with its source, for example `PHP 8.2 from composer.json, Node 22 from .nvmrc`.

### The Generated Config

From those values Knecht writes a `.ddev/config.yaml` into the checkout. For a Nuxt repo that pins Node 22 and has no `composer.json`, it looks like this:

```yaml
#knecht-generated
name: knecht-run-42
type: php
docroot: ""
webserver_type: generic
php_version: "8.4"
nodejs_version: "22"
omit_containers:
  - db
corepack_enable: true
disable_settings_management: true
```

The project type is `php`, because DDEV makes no CMS assumptions for it. The web server is [`generic`](https://docs.ddev.com/en/stable/users/configuration/config/#webserver_type){rel="&#x22;nofollow&#x22;"}, so neither nginx nor php-fpm runs, since without a website there is nothing to serve. The database container is left out, Corepack is enabled, and DDEV writes no settings files into the repo. Ports, environment variables and daemons go into Knecht's own override files next to it, as with every project. More on those below.

Knecht needs the comment on the first line so that on every further run it can tell for sure that this is a project without its own DDEV config, even though there is one in the checkout now.

The marker also makes sure none of this ends up in a commit. The Git actions in a run commit everything that is in the checkout. So before the first run Knecht writes the `.ddev/` directory into the clone's [`.git/info/exclude`](https://git-scm.com/docs/gitignore){rel="&#x22;nofollow&#x22;"} file. That is an ignore list that applies only to this clone and is not part of the repo itself, Git treats its entries like a `.gitignore`. For a repo with its own config only Knecht's own files go in there, for a generated one the whole directory, because DDEV also drops files into it on start. Which case applies, Knecht reads off the marker.

### Package Manager

npm is part of the DDEV image and the default when the repo sets nothing else. [Corepack](https://nodejs.org/api/corepack.html){rel="&#x22;nofollow&#x22;"} is enabled in every generated environment, so pnpm and yarn run without an install. Corepack downloads the version from the `packageManager` field, nothing has to be installed in the repo.

[bun](https://bun.sh/){rel="&#x22;nofollow&#x22;"} is missing from the image. Knecht adds one line to the image build that installs bun through npm. The layer stays in the [Docker cache](https://docs.docker.com/build/cache/){rel="&#x22;nofollow&#x22;"}, only the first bun session on a server builds it.

The downloads of all four go into DDEV's server-wide cache. DDEV points Composer, npm and Corepack there itself, Knecht adds the paths for the pnpm store, yarn and bun, for every project, including one with its own DDEV config. A server downloads each package once, later sessions install from the cache.

### Node Version

Concrete versions like `22` or `v20.11` are taken up to the minor version, [nvm](https://github.com/nvm-sh/nvm#nvmrc){rel="&#x22;nofollow&#x22;"} code names like `lts/iron` as their major version. Moving targets like `lts/*` or `latest` are not pinned. The default applies then, with a warning in the run log. [`engines.node`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines){rel="&#x22;nofollow&#x22;"} in `package.json` is usually a range like `>=20`. If the DDEV default satisfies the range, it stays, otherwise Knecht takes the highest LTS version that does.

### PHP Version

The choice is the versions of the DDEV image, currently 5.6 to 8.4. Composer [constraints](https://getcomposer.org/doc/articles/versions.md){rel="&#x22;nofollow&#x22;"} like `^8.1` or `>=8.1,<8.3` are translated into a [semver range](https://github.com/npm/node-semver#ranges){rel="&#x22;nofollow&#x22;"}, and Knecht takes the highest version that satisfies it. If none does, the default applies, with a warning in the run log.

### The Result in the Settings

![Project settings of a Nuxt repo without a DDEV config: the "Environment" card with PHP 8.4, Node 24 and pnpm, below it the boot commands and the "Dev Server" card with command and port](https://knecht.works/assets/knecht-project-settings-noddev.png)

The "Environment" card in the project settings shows the detected values with their source. If you want, you pick a different PHP version, a different Node version or a different package manager there. Detection already runs when you connect the repo, through the GitHub API and with the same logic as the boot. Warnings, for example about a constraint no version satisfies, show up in the card as well.

## Preview

A generated environment has no website. That is why there is a "Dev Server" card with the command that starts the dev server, for example `npm run dev`, and its port. Knecht starts it after the boot commands and serves it as the session's preview. The command receives the preview URL as `KNECHT_PREVIEW_URL`. Without a dev server the environment boots without a preview. Changes to the "Environment" and "Dev Server" cards take effect with the session's next run.

:update-video{caption="A Nuxt dev server as the preview. The code change shows up without a reload." src="https://knecht.works/assets/hmr-nuxt-knecht.mp4"}

### Hot Reload

Hot reload works in the preview like it does locally, without changes in the repo. Getting a Vite dev server through took some work, though.

::steps{level="4"}
#### The Daemon in the Container

The dev server runs as a daemon under [supervisord](https://supervisord.org/){rel=""nofollow""} in the web container, the way DDEV intends for [web\_extra\_daemons](https://docs.ddev.com/en/stable/users/configuration/config/#web_extra_daemons){rel=""nofollow""}. Knecht adds it to its override file, together with the forwarder from the next step:

```yaml
web_extra_daemons:
  - name: knecht-dev
    command: bash -lc 'npm run dev'
    directory: /var/www/html
  - name: knecht-forward
    command: knecht-forward 41000 3000
    directory: /var/www/html
```

The command runs in a login shell so the image's profile applies. DDEV starts the daemon right after `ddev start`, before the boot commands have run `npm ci`. So the first start dies, and supervisord gives up after a few attempts. Knecht restarts the daemon group after the boot commands and then polls until something answers on the port. Only then does the preview count as ready.

#### The Forwarder

Vite, Nuxt and Next bind to `127.0.0.1` only by default. The preview proxy reaches the container from outside though, through its IP on the Docker network. So a small forwarder runs next to it as a second daemon, a Node script of a few lines. It listens on all interfaces of the container on a fixed port and passes every TCP connection on to `127.0.0.1` and the dev server's port. Everything from the host targets the forwarder, the boot's polling included, so the same path is checked that the browser takes later.

#### The Proxy

A request to `<session>.preview.<host>` lands at Knecht's preview proxy. It checks the login cookie, resolves the IP of the web container and passes the request on to the forwarder over HTTP. The `Host` header stays the preview host, because the dev server has no hostname of its own. Hot reload runs over a [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API){rel=""nofollow""} connection. The proxy forwards the upgrade to the same port and passes along the subprotocol the browser asked for, because Vite only completes the HMR upgrade with `vite-hmr`. Since the forwarder passes raw TCP, the WebSocket gets through without anything else.

#### The Host Check

Vite rejects requests for unknown hostnames, see [server.allowedHosts](https://vite.dev/config/server-options.html#server-allowedhosts){rel=""nofollow""}. Since Vite 5.4.12 and 6.0.9 the dev server reads one extra allowed host from the environment variable `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS`, and Knecht sets it to the preview host. Nuxt uses Vite and is covered by that. Next.js keeps its own list in [`allowedDevOrigins`](https://nextjs.org/docs/app/api-reference/config/next-config-js/allowedDevOrigins){rel=""nofollow""}, which still comes from the repo.
::

### A Dev Server Next to Your Own Config

Since the same release a repo with its own DDEV config can name a dev server too, for example Vite for HMR next to a [Craft](https://craftcms.com/){rel="&#x22;nofollow&#x22;"} site. The dev server does not replace the site then. The repo's hostnames still reach the web server, and the dev server gets its own preview origin, which the container sees as `KNECHT_DEV_SERVER_URL`. That is where the repo points its asset URL, for example with an env value like `VITE_DEV_SERVER_PUBLIC=$KNECHT_DEV_SERVER_URL` in the project settings.

The page loads the dev server as a module script, and browsers fetch module scripts across origins without cookies. So the preview's login cookie never arrives there. That is why the dev server's origin carries a per-session token in its hostname instead of relying on the cookie. None of this is visible, `KNECHT_DEV_SERVER_URL` holds the finished URL.

## Learned Along the Way

Part of the work on this release was less about detection and more about how things fit together with DDEV, Docker Compose and Nuxt. Five things from that are useful outside Knecht too.

### DDEV Merges by File Name

DDEV reads every `config.*.yaml` in `.ddev/` and merges them in alphabetical order. For scalars the last file wins, lists are joined ([docs](https://docs.ddev.com/en/stable/users/extend/customization-extendibility/){rel="&#x22;nofollow&#x22;"}). Knecht's override was called `config.knecht.yaml`. A repo with a `config.vite.yaml` sorted after it and could override the run name or the environment. Knecht's files are now called `config.zzz-knecht.yaml` and `docker-compose.zzz-knecht.yaml`, so they are read last.

The merge also ignores zero values. An `xdebug_enabled: false` in an override file does not cancel a `true` from the main config. No debugger runs on a Knecht server, and every request would have waited for one. So Knecht turns Xdebug off through [`XDEBUG_MODE=off`](https://xdebug.org/docs/all_settings){rel="&#x22;nofollow&#x22;"} in the environment. The variable beats the ini, for php-fpm and the CLI. Your own `XDEBUG_MODE` line in the project settings still wins.

### Variables Without a Router

Without a router DDEV leaves [`DDEV_PRIMARY_URL`](https://docs.ddev.com/en/stable/users/extend/custom-commands/#environment-variables-provided){rel="&#x22;nofollow&#x22;"}, `DDEV_HOSTNAME` and `DDEV_SCHEME` empty. There is no router on Knecht servers, the preview proxy talks to the web containers directly. But the settings files DDEV itself writes for Drupal, TYPO3 and WordPress build their URLs from exactly these variables, so they pointed nowhere. Knecht now writes them itself, the way DDEV does locally, with the session's preview URL as the value.

### Ports From the Project List

Two parallel runs of the same project need different host ports, even when the repo pins a [`host_db_port`](https://docs.ddev.com/en/stable/users/configuration/config/#host_db_port){rel="&#x22;nofollow&#x22;"} for a developer's GUI client. Knecht asked the operating system for free ports, and DDEV refused the start anyway:

```text
host port 36865 has already been allocated to project knecht-run-6
```

DDEV remembers the ports of every project in `~/.ddev/project_list.yaml`, stopped ones included, and checks against that list. Knecht now reads the list too and keeps going until it has ports DDEV does not know.

### Docker Compose Expands Against the Host

The env values from the project settings reach the container through a Compose file. Docker Compose [interpolates](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/){rel="&#x22;nofollow&#x22;"} a `$NAME` in that file against the host's environment, not the container's. An unset name became an empty string, a password with a `$` arrived mangled. Knecht now expands references itself, against `KNECHT_PREVIEW_URL` and the earlier lines, and escapes every remaining `$` as `$$`. So `APP_URL=$KNECHT_PREVIEW_URL` becomes the session's preview URL, `SITE_URL=${APP_URL}/en` builds on it, and a `$` in a password stays a `$`.

### Nuxt Behind Nuxt

The dashboard is a Nuxt app, and the preview of a Nuxt project runs through a proxy in the same app. Both serve their assets under `/_nuxt/`. [Vite](https://vite.dev/){rel="&#x22;nofollow&#x22;"}'s dev middleware and [Nitro](https://nitro.build/){rel="&#x22;nofollow&#x22;"}'s static handler answer requests on that path before any server middleware gets a turn. So the preview's assets arrived at the dashboard and went nowhere, a 404 in production and ENOENT in dev mode. The fix is one line in `nuxt.config.ts`, [buildAssetsDir](https://nuxt.com/docs/api/nuxt-config#buildassetsdir){rel="&#x22;nofollow&#x22;"} set to `/_knecht/`. If you proxy a Nuxt app through a Nuxt app, you need it too.

## Limitations

The generated environment is a DDEV project with PHP and Node, nothing more. That runs everything that gets by with those two, so libraries, plugins, frontends and Node tools. Anything beyond that still needs its own `.ddev/config.yaml` in the repo:

- a database, because the generated environment has no database container
- additional services like Redis or Elasticsearch
- other runtimes like Python, Ruby or Go, which the DDEV image does not ship

Repos that bring their own docker-compose file instead of DDEV still cannot be booted by Knecht.

::callout{color="neutral" icon="i-lucide-arrow-right"}
Cases where a project runs differently on Knecht than locally are collected in the docs under [Troubleshooting](https://knecht.works/docs/resources/troubleshooting), with the fix per framework.
::


# Back to the Shared Daemon, One Preview for 180 MB

::note
This post continues [From the shared Docker daemon to a sandbox per run](https://knecht.works/updates/dashboard-architecture). That post explains why we selected a separate sandbox per run. This post explains why we removed it again.
::

The last architecture post ended with a clear plan. Each run gets its own [Sysbox](https://github.com/nestybox/sysbox){rel="&#x22;nofollow&#x22;"} sandbox with its own [Docker daemon](https://docs.docker.com/get-started/docker-overview/#docker-architecture){rel="&#x22;nofollow&#x22;"}. We built it, and it worked. Still, we removed the sandbox again, because two problems could wait no longer. We postponed both problems on purpose before.

## The cost

A Sysbox sandbox is basically a small operating system with [systemd](https://systemd.io){rel="&#x22;nofollow&#x22;"}, its own Docker daemon, and the complete [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} stack on top. We knew from the start that this uses many resources. We thought we could control the cost later, but we could not.

- One active preview used about 3 GB of RAM in our measurements. With 20 parallel previews, that would be 60 GB, only for sandboxes.
- Each sandbox needs its own copy of all DDEV images, and that is 1-2 GB of disk per preview. A registry cache made the downloads faster, but it did not change the disk use.

The goal of Knecht is that an agency operates all its projects on one affordable server. An architecture with 3 GB per preview is the wrong base for this goal, no matter how clean its isolation is.

## What the sandbox solved

As a reminder, the last post gave two reasons for the sandbox.

- On the shared daemon, there was no isolation between runs. The fixed ports of the [DDEV router](https://docs.ddev.com/en/stable/users/usage/architecture/){rel="&#x22;nofollow&#x22;"} collided. Therefore we had to remove the router and change the DDEV config.
- The agent executes external code, and a process that reaches the [Docker socket](https://docs.docker.com/engine/security/#docker-daemon-attack-surface){rel="&#x22;nofollow&#x22;"} of the host controls the complete server.

The sandbox solved both problems at once. But it was the most thorough solution, not the only one. We could only remove it after we examined both problems again, one by one.

## The new solutions

### No socket in the run

The problem is the Docker socket. The agent executes external code. When the socket is in the environment of the agent, a hijacked agent controls the complete server. The sandbox therefore gave each run its own daemon, so the socket of the host stayed out of reach.

Our new solution starts earlier. The run gets no Docker access at all. Knecht starts DDEV on the host side. The agent and all project commands, for example `composer install`, run only in the web container of the project. An agent that an attacker hijacks with [prompt injection](https://simonwillison.net/series/prompt-injection/){rel="&#x22;nofollow&#x22;"} then sits in a normal container with its own network and limited resources. It finds no socket and no daemon there.

### Rename instead of isolate

The port collisions came only from the router. The router is the reverse proxy that DDEV puts in front of all projects, and it binds ports 80 and 443 on the host. The router stays removed. Instead, the preview proxy connects to the web container of each run directly over the [Docker network](https://docs.docker.com/engine/network/){rel="&#x22;nofollow&#x22;"}.

The proxy must supply one thing, the hostname. Projects with multiple domains, for example a [Craft multisite](https://craftcms.com/docs/5.x/system/sites.html){rel="&#x22;nofollow&#x22;"}, select the site from the requested domain. But the preview runs under a Knecht URL, not under the real domain of the project. Therefore the proxy sends the real domain in the [Host header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Host){rel="&#x22;nofollow&#x22;"}. For the project, each request looks as if it came over the normal URL.

Parallel runs of the same project must not conflict with each other. Therefore Knecht registers each run as a separate DDEV project with a unique name. The change to the DDEV config, a minus point in the last post, remains, but the project does not see it. The code in the repo stays untouched. Knecht only rewrites the generated runtime config.

## The tradeoff

For security, this is a step back compared with Sysbox. Sysbox mapped root in the container to an unprivileged host user with [user namespaces](https://man7.org/linux/man-pages/man7/user_namespaces.7.html){rel="&#x22;nofollow&#x22;"}. Now the containers run again with [runc](https://github.com/opencontainers/runc){rel="&#x22;nofollow&#x22;"}, the normal Docker runtime, and the border to the host is thinner. The points above compensate for this, because the run has no socket, its own network, and fixed limits.

The [threat model](https://owasp.org/www-community/Threat_Modeling){rel="&#x22;nofollow&#x22;"} decides if this step back is acceptable, as in the last post. Knecht runs at an agency, for its own projects, on its own server. The attacker that the sandbox would block in addition needs a kernel exploit. This attacker then lands on a server that only contains the projects of the agency. To pay 3 GB instead of 180 MB per preview for this risk is the wrong trade.

## The result

Both variants ran on the same dev machine, measured in July 2026:

|                          | Sandbox per run (Sysbox)         | DDEV on the host (today)           |
| ------------------------ | -------------------------------- | ---------------------------------- |
| RAM per active preview   | \~3 GB                           | \~180 MB                           |
| DDEV images              | per sandbox, 1-2 GB extra        | once per host                      |
| Wake a stopped preview   | minutes, a complete sandbox boot | seconds                            |
| Docker access in the run | own daemon in the sandbox        | none, Knecht controls from outside |
| Isolation border         | own daemon plus user namespaces  | own network, limits, no socket     |

Two smaller optimizations come on top.

- The database of a preview runs with a leaner configuration. The MySQL config that DDEV supplies permits about 1 GB of [buffer](https://mariadb.com/kb/en/innodb-buffer-pool/){rel="&#x22;nofollow&#x22;"} for each database.
- A stopped preview uses 0 RAM. Only the database volume and the code remain.

Before, one server could hold a few previews. Now it can hold almost all projects of an agency at the same time.

## What we learned

The last post started with the sentence that we test the riskiest assumption first. That was correct, and it worked, the sandbox ran. But the correct last question is not if the system runs. The correct question is if it runs at a cost that matches the goal. You can only answer this question when the system is under real, parallel load. We now make this measurement earlier.


# Knecht Now Replies on GitHub

Until now, everything in Knecht flowed in one direction. A [trigger](https://knecht.works/updates/workflow-engine) fired, a workflow ran, and the result sat in the dashboard. Anyone waiting for an answer in the GitHub issue saw nothing there. With this update, Knecht works where the work is reported. It replies and labels directly in the issue thread, and a mention in a comment sends it back to work.

## From bug report to PR

This is what it looks like on our Craft test project. Someone files an issue saying the site has no dark mode. A trigger starts the "Classify Issue" workflow. Knecht boots the site in its [preview environment](https://knecht.works/updates/sandbox-rollback), reproduces the report, and finds out that dark mode was simply never implemented. It applies the existing `enhancement` label and answers the reporter in the thread.

![GitHub issue with a dark mode bug report, below it the knecht-works app has applied the enhancement label](https://knecht.works/assets/issue-creation-with-label.png)

The reply contains the findings and a concrete plan for the implementation, with the preview URL at the end.

![Comment by the knecht-works app in the issue with findings and an implementation plan, below it a comment by the team member with a mention and an eyes reaction](https://knecht.works/assets/issue-follow-up.png)

A team member reads the analysis and replies with a mention, roughly "@knecht-works, implement it and open a PR". Knecht confirms right away with an eyes reaction and continues working, in the same environment and the same conversation as the triage. So it already knows the findings and the plan. A few minutes later the answer is in the thread, with the opened PR and the preview URL.

![Reply by the knecht-works app in the issue with a summary of the two commits, at the end the preview URL and the PR link](https://knecht.works/assets/issue-enhancement-finished.png)

The fix can build on the triage because of the biggest change in this update, sessions.

## One session per issue

Until now, every workflow execution was its own world, with its own checkout, its own environment, and its own agent conversation. While building the reply loop it became clear that this is the wrong unit, because the environment and the context belong to the issue, not to a single execution. So there are sessions now. A session belongs to exactly one issue or PR and holds its checkout, its environment, and one shared agent conversation. Inside it run the runs, that is, individual workflow executions, and follow-ups, that is, individual messages to the agent.

![Project page in the Knecht dashboard with the run list grouped by issues, under the dark mode issue four runs from the triage to two mentions](https://knecht.works/assets/knecht-project-triggers-in-action.png)

The project page and the runs overview now group runs by session. In the screenshot, four runs belong to the dark mode issue, from "Classify Issue" to the two mentions, all in the same environment. In detail this means:

- If two triggers fire on the same issue, they run one after the other in the session, never in parallel.
- If the issue is closed, the session closes too. A reopen revives it, as long as its environment still exists.
- When archiving an environment, Knecht now also saves the agent's conversation, a few megabytes. It survives an archive and restore cycle.
- Events without an issue or PR, that is, push, schedule, and manual start, behave as before and get a session holding a single run.

If an environment is torn down completely, the conversation is gone. The agent then does not silently start from zero. It reads the GitHub thread, the results of the previous actions, and the [project memory](https://knecht.works/updates/agent-memory), and says in the thread that it is starting fresh. Existing installations do not have to do anything for this, the update automatically converts existing runs and environments to sessions on startup.

## The Cloudflare example

Cloudflare showed in August 2026 that issue triage can be automated end to end, on the repository of the Astro framework. Their [triage system](https://blog.cloudflare.com/astro-issue-triage/){rel="&#x22;nofollow&#x22;"} reproduces every report, diagnoses the cause, and builds the fix. The open issues dropped from over 200 to about 30 with it. It is its own piece of software though, built by a team at Cloudflare for exactly this repository. In Knecht, the same flow is a workflow that you put on your own projects, and the session brings the booted site with it.

## What is next

Next up is Jira. The concepts stay the same, a ticket gets its session with an environment and a conversation, and replies and mentions work in the ticket just like in the issue thread.


# What Knecht Does

A bug report always starts with an attempt to reproduce the error. After the fix, you must make sure that the error is really gone. This sounds simple, but often it is not.

## Motivation

Agencies often maintain many projects. These projects often have different configurations, or they run only on the computer of the one employee who was there from the start. Still, all projects need regular security updates and bug fixes.

AI agents can only really help here when the projects boot completely.

### Security Updates

To install a security update in a CMS, the database must run in almost all cases. After an update, database migrations can follow. Thus Dependabot and other bots cannot just do a `composer update` and deploy the result.

### Bug fixes

Unfortunately, a bug fix is not always this simple.

::prompt{description="Pls fix!"}
<https://youtu.be/dQw4w9WgXcQ?t=0>{rel=""nofollow""}
::

For a bug fix, an employee must first be available. In the best case, this employee already has the project on the local machine and can solve the error at the root. Often, no such employee is available.

## DDEV

DDEV is a development environment that is based on Docker. With DDEV, you can run a full project. You do not need to install developer tools directly on your device.

Each project boots in a reproducible and isolated way. The web server and the database start with a clean configuration, always in the same way. This reliability is the base for everything else. When a project always boots in the same way at the push of a button, a machine can also boot it.

## What Knecht does

We build Knecht as a dashboard that you host on your own server. Thus you keep your data. The dashboard shows preview links and screenshots (made with Penthouse). With them, you can verify a bug fix directly.

### How it works

Knecht has projects, workflows, and triggers.

::steps{level="3"}
### Projects

A project is always a GitHub repository in which DDEV is already configured. In the project, you can also set environment variables and the database.

### Workflows

A workflow is a predefined process that works with projects. One example is this sequence: boot the project → update the Composer packages → create a PR with the changes. Knecht does these steps in a deterministic order.

But bug fixes are rarely the same repeatable steps. For them, Knecht uses AI agents. Through Opencode, the agents can reproduce and repair a bug in the booted project.

### Triggers

A trigger is the start point of a workflow. Through webhooks, for example from Jira or GitHub, Knecht can start predefined workflows automatically. Knecht then delivers the results as a pull request.
::


# A Terminal and VS Code for Each Run

A run is a single execution of a [workflow](https://knecht.works/updates/workflow-engine) on a project, with its own environment on the server. Before, the dashboard was the only way to this environment. You could send instructions to the agent and view the preview, but you could not enter the environment yourself. To read a log or to test a command, you had to ask the agent. Now the run page has three direct ways in.

## The terminal

The most direct way into a run is a shell. It exists in two variants, in the browser for each dashboard member, and over SSH for people who already have access to the server. The video shows both.

:update-video{caption="The terminal in the browser and the ready SSH command" src="https://knecht.works/assets/knecht-ssh-showcase.webm"}

### In the browser

A click on "Terminal" opens a shell in the container of the run. The shell opens as a window directly on the run page. You type in the same browser tab in which you view the run. You do not need a terminal program or an SSH client on your own computer.

- It works for each dashboard member, without any access to the server.
- The shell runs in the same container as the agent. Composer, npm, and Git are there, and they behave like in the real project.
- No additional port opens. The terminal uses the same HTTPS connection as the dashboard.
- If a run has multiple containers, for example its own database, the terminal shows one tab per service.

::note
Knecht stops the environment of a run automatically when nobody uses it for a while, so it does not use RAM. Work in the terminal counts as use. The environment stays on while you type in it.
::

### Over SSH

If you prefer your own terminal, the terminal window shows a ready SSH command that you can copy. Paste it on your own machine, and you land in exactly the same container.

```bash
ssh -t knecht@my-server.com docker exec -it -u 1000:1000 -w /var/www/html -e HOME=/home/node -e USER=node ddev-knecht-run-4-web bash -l
```

Knecht does not operate its own SSH server, and it does not manage keys. The command uses the SSH access to the server that already exists. You store the SSH address of the server once in the settings, nothing more. This way is therefore only for people who already have access to the server. All others use the web terminal.

## VS Code in the browser

VS Code runs directly in the run. A click on "Open in VS Code" on the run page opens the IDE in a new browser tab. The base is [openvscode-server](https://github.com/gitpod-io/openvscode-server){rel="&#x22;nofollow&#x22;"}, the open source build of VS Code for the browser.

:update-video{caption="VS Code opens the run in the browser" src="https://knecht.works/assets/knecht-vs-code.webm"}

The IDE works directly on the project in the run, not on a copy. A saved change is immediately in the active project. It is the same code that the preview and the agent see. And because each run is a full Git clone, commits and branches work normally in the IDE and in the terminal.

You do not need a local setup. The IDE runs in the browser for each dashboard member. Like the previews, you can only reach it with a Knecht login.


# Automate DDEV Projects with Workflows

A workflow is a list of steps that Knecht executes automatically for a project. For example, start the project, update the Composer packages, run the tests, and open a pull request. Almost all of the last weeks went into this engine. This post explains what the engine can do, what separates the AI action from a chat, and what is still absent.

![The workflow editor with trigger, steps, and the action library](https://knecht.works/assets/workflow-detail.png)

## How a workflow runs

When a workflow starts, Knecht creates a **run**, a single execution on a project. Each run gets its own, isolated environment, the **sandbox**. The complete project runs in it. The code comes fresh from GitHub, Knecht imports the database, and [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} starts. The live system and other runs do not notice it. The [architecture post](https://knecht.works/updates/dashboard-architecture) explains why each run gets its own sandbox.

The steps run one after the other, and each step leaves results. Later steps insert these results with placeholders.

```text
{{ steps.run_tests.stdout }}      the output of the step "Run tests"
{{ inputs.title }}                the title of the ticket that started the workflow
```

You do not need to memorize this. When you type `{{ `, a list shows everything that is available at this position. And after each step, Knecht saves what happened. Therefore you see live where a run is, and you can continue a failed run exactly from the step where it stopped.

## The actions

Each step executes one action. There are roughly three types.

::field-group
  :::field{name="Deterministic actions"}
  They do exactly one task, always in the same way. They boot the project, execute a shell command like `composer update`, run your own JavaScript code, call an external URL, check the complete sitemap for broken links, or bring the changes back to GitHub as a pull request.
  :::

  :::field{name="Control flow actions"}
  If/else executes steps only under a condition, for example "when the tests failed". Loop repeats steps for each entry of a list.
  :::

  :::field{name="AI action"}
  It lets an agent work in the active project. More about this below.
  :::
::

Not every error is a real error, so each step has its own error policy. Unstable commands get retries with backoff, and with `continueOnError` the run continues after an error. The library still grows. The screenshot above shows a part of the current actions.

### An agent, not a chat

The AI action starts [opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"} with your own API key directly in the sandbox. The agent works in the real, active project. It reads code, changes files, and executes commands. A chat tells you what a fix could look like. The agent applies the fix and tests if it works.

![The AI action with prompt, fixed output format, and the available variables](https://knecht.works/assets/workflow-ai-action.png)

Instead of free text, the agent can deliver fixed output fields like `prTitle`, as validated JSON for later steps. And the agent does not disappear after the run. A chat on the run page continues the same session. "Make the button blue" does not need a new run.

### Locked in the sandbox

Everything that a workflow executes (shell commands, your own code, the agent) runs only in the sandbox, never on the server itself.

Project secrets also stay where they belong. Knecht stores API keys and tokens [encrypted](https://knecht.works/updates/gh-auth-evolution) in the database. The preview URLs are also not public. To open one, you need a Knecht login.

## The triggers

A trigger defines when a workflow starts on its own. This is the point where a tool becomes automation, because nobody must remember to start the process. The workflow runs when its condition occurs, also at night and on the weekend. There are currently three types.

::field-group
  :::field{name="Manual"}
  With a click in the dashboard, or as a test run directly in the editor.
  :::

  :::field{name="Integrations"}
  Knecht reacts to events from GitHub and Jira. For example, when a Jira ticket gets the label "knecht", the workflow starts, and the link to the finished PR appears as a comment on the ticket.
  :::

  :::field{name="Cron"}
  On a schedule, for example a check of the security updates each Monday at 6:00.
  :::
::

A trigger can include multiple projects, and it starts a separate run for each project.

## After the start

Before you activate a trigger, you can test the workflow directly in the editor, against a real project in its own sandbox. The same rules apply to test runs and real runs.

![A test run directly in the editor, with live log and active step](https://knecht.works/assets/workflow-test-run.png)

Inside a run, everything runs one step after the other, on purpose. There are no parallel branches. A run stays a linear, traceable chain. You can configure how many runs execute at the same time. All runs above that limit wait in the queue.

## Workflows as code

You can export each workflow as YAML or JSON and import it again. Therefore a workflow can move into the Git repo, get reviews like all other code, and move between projects or instances. If you prefer a text editor, you write the file directly and import the finished file.

The format also opens a door for later. A workflow that works well at one agency works the same at the next agency, because it only contains steps and placeholders. A possible future step is a workflow store. There you install finished workflows, for example security updates or link checks, instead of a manual setup.

## What is still absent

A notification system does not exist yet. When a run fails, you only see it in the dashboard. If you want an immediate signal, call a Slack webhook with the HTTP step at the end of the workflow. A hard time limit per run is also absent. A stuck step runs until you stop it.


# Datenschutzerklärung

## Verantwortlicher

Verantwortlich für die Datenverarbeitung auf dieser Website ist:

E-Mail: <hallo@knecht.works>

## Erhebung und Verarbeitung personenbezogener Daten

Wir verarbeiten personenbezogene Daten nur, soweit dies zur Bereitstellung einer
funktionsfähigen Website sowie unserer Inhalte und Leistungen erforderlich ist.

## Warteliste / Newsletter

Trägst du dich in die Warteliste ein, verarbeiten wir deine E-Mail-Adresse
ausschließlich, um dir Produkt-Updates und Beta-Informationen zuzusenden. Die
Einwilligung kann jederzeit mit Wirkung für die Zukunft widerrufen werden.

## Deine Rechte

Du hast das Recht auf Auskunft, Berichtigung, Löschung, Einschränkung der
Verarbeitung, Datenübertragbarkeit sowie Widerspruch gegen die Verarbeitung.

## Hosting

Diese Website wird bei [Cloudflare](https://cloudflare.com){rel="&#x22;nofollow&#x22;"} gehostet. Details zur Datenverarbeitung
durch den Anbieter findest du in dessen Datenschutzerklärung.


# Impressum

## Angaben gemäß § 5 TMG

**Knecht**:br
Leonfeldner Straße 90a :br
4040 Linz :br

## Kontakt

E-Mail: <hallo@knecht.works>

## Vertreten durch

[Samuel Reichör](https://samuelreichor.at){rel="&#x22;nofollow&#x22;"}:br
Leonfeldner Straße 90a :br
4040 Linz :br

## Umsatzsteuer-ID

Umsatzsteuer-Identifikationsnummer gemäß § 27a Umsatzsteuergesetz:

USt-Id Nr.: ATU82964259
Steuer Nr.: 52 392/4660


# Der Agent bekommt ein Gedächtnis pro Projekt

Die [AI-Action](https://knecht.works/updates/workflow-engine) startet für jeden Run eine frische [Sandbox](https://knecht.works/updates/sandbox-rollback) mit einem eigenen Checkout des Projekts. Der Agent wusste darin bisher nichts von früheren Runs. Was er über ein Projekt herausgefunden hatte, war danach weg, und der nächste Run musste es neu erkunden. Jetzt legt Knecht pro Projekt Notizen an. Der Agent schreibt sie selbst und findet sie beim nächsten Run wieder vor.

## Jeder Run fing bei null an

Wir haben uns im August 2026 angeschaut, wo langsame Runs ihre Zeit verlieren. Ein großer Teil war Wiederentdeckung. Eine einzeilige Änderung an einem `font-weight` dauerte auf einem Projekt, das schon Dutzende Runs hinter sich hatte, 280 Sekunden. Rund 160 davon verbrachte ein Subagent damit herauszufinden, wo die Styles liegen und wie das Projekt gebaut wird, also Fakten, die frühere Runs längst kannten.

[opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"}, der Agent hinter der AI-Action, kennt von Haus aus nur statische [Regel-Dateien](https://opencode.ai/docs/rules/){rel="&#x22;nofollow&#x22;"} wie eine `AGENTS.md` im Repository. Die schreibt ein Mensch von Hand, der Agent trägt dort selbst nichts ein. Es gibt Community-Plugins für gelerntes Memory, aber sie passen nicht zu Knecht.

- Alles, was ein Plugin auf die Platte schreibt, landet im Wegwerf-Checkout des Runs und ist danach weg. Die Persistenz außerhalb des Runs müsste Knecht also sowieso bauen.
- Das bekannteste Plugin, [opencode-mem](https://github.com/tickernelz/opencode-mem){rel="&#x22;nofollow&#x22;"}, speichert seine Erinnerungen erst, wenn in der Session eine Weile nichts passiert, also in der Pause, in der ein Mensch im Chat gerade nichts tippt. Knecht startet opencode aber [nicht-interaktiv](https://opencode.ai/docs/cli/){rel="&#x22;nofollow&#x22;"}, und dieser Prozess beendet sich sofort nach seiner Antwort. Die Pause gibt es nie, das Plugin würde also nie speichern.

Deshalb haben wir das direkt in Knecht gebaut, als kleinen Speicher pro Projekt auf dem Host, außerhalb jeder Sandbox.

## Ein Index und Themen-Dateien

Das Gedächtnis besteht aus einer Index-Datei `MEMORY.md` und beliebigen Themen-Dateien. Nach ein paar Runs auf einem [Craft](https://craftcms.com){rel="&#x22;nofollow&#x22;"}-Projekt kann es zum Beispiel so aussehen:

::code-tree{default-value="MEMORY.md"}
```md [MEMORY.md]
- Styles: Tailwind, tokens, build step, see styles.md
- Build and tests: commands and pitfalls, see build.md
```

```md [styles.md]
Tailwind 4, tokens live in src/css/config.css.
Font sizes and weights only via text-* utilities, no raw values.
After CSS changes run `ddev npm run build`,
templates load the built file from web/dist/.
```

```md [build.md]
Build: `ddev npm run build`
Tests: `ddev php vendor/bin/phpunit`
The build needs DDEV running, plain npm on the host
fails on the node version.
```
::

Der Index hält eine Zeile pro Thema und wird bei jedem Agenten-Aufruf in die Instructions gemischt, er ist also immer im Kontext. Damit das billig bleibt, ist er hart auf 2 KB begrenzt. Die Themen-Dateien liest der Agent nur, wenn der Index auf etwas Relevantes zeigt, sie kosten bis dahin keinen Kontext. Das Muster stammt aus Claude Code, dessen [Auto-Memory](https://code.claude.com/docs/en/memory){rel="&#x22;nofollow&#x22;"} genauso aufgebaut ist.

Gepflegt wird das Ganze vom Agenten selbst, nach Regeln in der `AGENTS.md`, die Knecht in jede Sandbox legt. Er soll Notizen umschreiben statt anhängen, Veraltetes löschen und Korrekturen festhalten, die im Follow-up-Chat auf der Run-Seite kommen. Wer dort einmal "nein, wir benutzen keine Utility-Klassen" schreibt, soll das kein zweites Mal schreiben müssen. Und er soll seine eigenen Notizen kurz prüfen, bevor er darauf aufbaut, denn das Projekt kann sich seit dem letzten Run geändert haben.

## Kopieren statt mounten

Vor jedem Agenten-Aufruf kopiert Knecht die Notizen in den Checkout des Runs, nach dem Aufruf zurück auf den Host. Das Zurückkopieren passiert auch bei fehlgeschlagenen Schritten, denn die Notizen halten Fakten über das Projekt fest, keinen Run-Status.

Ein Mount in die Sandbox wäre einfacher gewesen. Mit der Kopie arbeitet jeder Run aber nur auf seinem eigenen Stand, und Knecht hat beim Zurückkopieren eine Stelle, an der es prüfen kann, was der Agent geschrieben hat.

- Übernommen werden nur einfache Markdown-Dateien auf oberster Ebene, keine [Symlinks](https://man7.org/linux/man-pages/man7/symlink.7.html){rel="&#x22;nofollow&#x22;"}, keine Unterordner, keine versteckten Dateien.
- Der Index darf höchstens 2 KB groß sein, alle Dateien zusammen höchstens 64 KB. Ist die Kopie größer, übernimmt Knecht sie gar nicht, der letzte gültige Stand bleibt erhalten, und im Run-Log steht eine Zeile dazu.

Knecht verwirft zu große Kopien, statt sie zu kürzen, weil der Agent eine Kürzung nicht mitbekommen würde und dann mit lückenhaften Notizen weiterarbeitet. Mit dem alten Stand kann er beim nächsten Run selbst aufräumen, die Regeln dafür stehen in der `AGENTS.md`. Dass die Limits eingehalten werden, prüft Knecht trotzdem selbst, damit der Kontext nicht wächst, wenn das Modell die Regeln ignoriert.

## Was noch fehlt

Eine Ansicht in den Projekt-Einstellungen, die zeigt, was sich Knecht gemerkt hat, gibt es noch nicht. Dort will man die Notizen lesen und auch korrigieren können. Offen ist auch, ob Knecht eine zu große Kopie irgendwann zusammenfassen soll, statt sie zu verwerfen, das lohnt sich aber erst, wenn Verwerfungen in der Praxis häufig vorkommen.


# Beta Tester gesucht

Knecht läuft. Was ihm jetzt fehlt, sind echte Projekte, denn lokale Tests erzeugen keine echten Bugs. Deshalb suchen wir eine Handvoll Agenturen und Freelancer, die Knecht als Erste im Alltag einsetzen. Wenn du direkt dabei sein willst, trag dich im [Formular unter diesem Post](https://knecht.works/#cta) ein.

## Was ihr bekommt

Der Einstieg soll euch nichts kosten. Deshalb bekommt ihr von uns:

- Ihr müsst Knecht nicht selbst installieren. Wir hosten eure Instanz während der Beta und kümmern uns um Updates und Betrieb.
- 100 € OpenCode-Guthaben, damit die AI Agents sofort loslegen können.
- Das erste Jahr nach dem Release ist für euch kostenlos.
- Euer Logo mit Link auf der Startseite.

Ihr geht also kein finanzielles Risiko ein und startet mit einem lauffähigen Knecht, eingerichtet auf eure Projekte. Wer Knecht lieber auf dem eigenen Server betreibt, kann das weiterhin tun.

## Was wir brauchen

Im Gegenzug wünschen wir uns eine Person, die Knecht wirklich benutzt und uns regelmäßig sagt, wo er sie blockiert, was fehlt und was gut funktioniert. Mehr verlangen wir nicht. Dieses Feedback aus echten Projekten ist für uns mehr wert als jeder lokale Test.

## Für wen das passt

Am meisten bringt Knecht dort, wo viele Projekte gewartet werden. Ihr passt gut, wenn ihr mit DDEV arbeitet und genug Projekte betreut, dass Security-Updates und Bugfixes bei euch Routinearbeit sind. Wenn eure Projekte noch nicht auf DDEV laufen, sich aber leicht umstellen lassen, passt das auch.

## Mitmachen

Wenn das nach euch klingt, trag dich im [Formular direkt unter diesem Post](https://knecht.works/#cta) ein und wähle "Ich will aktiv mittesten & Feedback geben". Wir melden uns dann bei dir. Wenn du vorab Fragen hast, schreib uns an <hallo@knecht.works>.

Und wenn Testen gerade nichts für euch ist, ihr aber wissen wollt, wie es weitergeht, wählt im [Formular](https://knecht.works/#cta) einfach "Nur Updates bekommen".


# Vom geteilten Docker Daemon zur Sandbox pro Run

::note
Dieser Post ist ein Blick unter die Haube. Die Container-Architektur ist der Unterbau, damit parallele Previews mit DDEV-Projekten funktionieren, nicht das Produkt selbst. Was Knecht macht und für wen er gedacht ist, steht auf der [Startseite](https://knecht.works) und in [Was macht der Knecht](https://knecht.works/updates/was-macht-knecht).

Update, Juli 2026: Wir haben die Sysbox-Sandbox gebaut, und sie lief. Trotzdem haben wir sie wieder ausgebaut. Warum, steht in der Fortsetzung [Zurück zum geteilten Daemon](https://knecht.works/updates/sandbox-rollback). Der Weg zur Entscheidung unten bleibt trotzdem lesenswert, die Fortsetzung baut darauf auf.
::

Knecht läuft selbst als Docker Container, muss aber DDEV-Projekte hochfahren, die wieder aus Containern bestehen. Ob das überhaupt funktioniert, war die riskanteste Annahme der ganzen Architektur. Deshalb haben wir sie zuerst getestet, noch bevor der eigentliche Code entsteht.

## Der Ansatz

Kurz zum Hintergrund: Docker besteht aus zwei Teilen. Der [Docker Daemon](https://docs.docker.com/get-started/docker-overview/#docker-architecture){rel="&#x22;nofollow&#x22;"} ist der Dienst, der Container tatsächlich erstellt und verwaltet. Die Docker CLI ist nur ein Client, der über einen Unix-Socket (`/var/run/docker.sock`) mit dem Daemon spricht. Wer den Socket hat, steuert den Daemon.

Genau das nutzt Knecht: Der Container startet keinen eigenen Daemon, sondern mountet den Socket des Hosts und steuert damit den Host-Daemon. Das Muster heißt [Docker-out-of-Docker](https://www.avonture.be/blog/docker-out-of-docker-dood/){rel="&#x22;nofollow&#x22;"} (DooD). Die DDEV-Container laufen dann als Geschwister neben dem Knecht-Container auf dem Host, nicht verschachtelt in ihm. [Coolify](https://coolify.io){rel="&#x22;nofollow&#x22;"} und viele CI-Runner arbeiten genauso.

## Der Test

::steps{level="3"}
### Host-Daemon erreichbar

`docker ps` im Container zeigt die Host-Container. Der Socket-Mount funktioniert.

### DDEV-Projekt bootet

Ein minimales PHP-Projekt am festen Pfad, dann `ddev start`. DDEV startet Webserver und Datenbank auf dem Host.

### Container sind Host-Geschwister

Auf dem Host tauchen die Projekt-Container als normale Nachbarn des Knecht-Containers auf.

### App erreichbar

Das gebootete Projekt antwortet. Wichtig dabei: `*.ddev.site` löst per DNS immer auf `127.0.0.1` auf, also auf den Container selbst. Der Preview-Proxy muss den Web-Container deshalb direkt über das Docker-Netzwerk ansprechen.
::

Damit ist die Basis bewiesen: Ein Prozess im Knecht-Container kann echte DDEV-Stacks booten, mit korrekt gemountetem Source Code.

## Zwei Probleme sind geblieben

Der Test hat aber auch die Grenzen des Ansatzes gezeigt.

### Keine Isolation zwischen Runs

Alles läuft auf einem gemeinsamen Daemon. Knecht soll aber mehrere Previews parallel fahren, ohne dass sich Runs gegenseitig stören. Wir mussten sogar den [DDEV-Router](https://docs.ddev.com/en/stable/users/usage/architecture/){rel="&#x22;nofollow&#x22;"} weglassen. Das ist der Reverse Proxy, den DDEV vor alle Projekte stellt und der die Ports 80 und 443 auf dem Host bindet. Feste Host-Ports gibt es nur einmal, bei vielen parallelen Projekten kollidiert das. Ohne Router muss Knecht in die `.ddev/config.yaml` eingreifen und zum Beispiel dir Urls überschreiben.

### Fremder Code am Host-Socket

Der Agent führt Code aus, und wir kontrollieren nicht vollständig, was er tut. Ein Agent lässt sich über [Prompt Injection](https://simonwillison.net/series/prompt-injection/){rel="&#x22;nofollow&#x22;"} kapern, etwa durch manipulierte Inhalte im Repo oder in einer Datenquelle, und macht dann nicht mehr das, was wir wollten. Wer an dieser Stelle an den Host-Socket kommt, steuert den Daemon, und wer den Daemon steuert, kann jeden Container mit jedem Mount starten. Das ist faktisch Root auf dem Server.

## Die Lösung: eine Sandbox pro Run

Beide Probleme haben dieselbe Antwort: Jeder Run bekommt seinen eigenen Docker Daemon in einer eigenen Sandbox. Damit verschwindet auch der Grund, den Router wegzulassen. Port 80 in Sandbox A kann nicht mit Sandbox B kollidieren, weil jede Sandbox ihren eigenen Netzwerk-Namespace hat. Projekte laufen also wieder mit allen ihren URLs und Settings.

Bleibt die Frage, was die Sandbox ist. Wir haben uns die üblichen Kandidaten angesehen.

### Privileged Docker-in-Docker

Ein zweiter Daemon in einem Container mit [`--privileged`](https://docs.docker.com/engine/containers/run/#runtime-privilege-and-linux-capabilities){rel="&#x22;nofollow&#x22;"}. Die Flag schaltet praktisch alle Schutzmechanismen ab und gibt dem Container Zugriff auf die Host-Geräte. Eine bösartige Dependency kommt damit ohne Exploit auf den Host. Fällt raus.

### Kata Containers

[Kata](https://katacontainers.io){rel="&#x22;nofollow&#x22;"} startet jeden Container in einer leichtgewichtigen VM mit eigenem Kernel. Das ist die stärkste Grenze und der Ansatz hinter [Firecracker](https://firecracker-microvm.github.io){rel="&#x22;nofollow&#x22;"}, auf dem etwa AWS Lambda läuft. Kata braucht aber `/dev/kvm`, und normale Cloud-VPS bieten [keine Nested Virtualization](https://lowendtalk.com/discussion/154261/searching-vps-for-nested-virtualization){rel="&#x22;nofollow&#x22;"}. Das würde Bare-Metal erzwingen und kollidiert mit dem Ziel, Knecht auf einem normalen VPS zu installieren. Fällt raus.

### gVisor

[gVisor](https://gvisor.dev){rel="&#x22;nofollow&#x22;"} fängt Syscalls in einem Userspace-Kernel ab und braucht kein KVM. Es isoliert Anwendungsprozesse gut, tut sich aber schwer damit, selbst ein Docker-Host zu sein: [iptables wird nur teilweise unterstützt](https://github.com/google/gvisor/issues/9917){rel="&#x22;nofollow&#x22;"} und [Overlayfs bricht mit Docker v29](https://github.com/google/gvisor/issues/12475){rel="&#x22;nofollow&#x22;"}. Genau ein Docker-Host ist aber, was DDEV braucht. Fällt raus.

### Unsere Wahl: Sysbox

[Sysbox](https://github.com/nestybox/sysbox){rel="&#x22;nofollow&#x22;"} ist eine Container-Runtime, die Docker-in-Docker ohne `--privileged` erlaubt. Sie nutzt dafür [User Namespaces](https://man7.org/linux/man-pages/man7/user_namespaces.7.html){rel="&#x22;nofollow&#x22;"}, Root im Container wird auf einen unprivilegierten User auf dem Host gemappt. Sysbox ist genau für diesen Fall gebaut, braucht kein KVM und läuft damit auf jedem normalen Linux-Server.

## Das Threat Model entscheidet

Den Ausschlag gibt am Ende nicht die Runtime, sondern das Threat Model, also die Frage, wer hier eigentlich angreift und was er erreicht. Knecht ist [Single-Tenant](https://www.geeksforgeeks.org/system-design/single-tenant-vs-multi-tenant-architecture/){rel="&#x22;nofollow&#x22;"}: eine Agentur, ihre Projekte, ihr Server. Die VM-Grenze von Kata schützt vor allem davor, dass ein Kunde aus seiner Umgebung in die eines anderen ausbricht. Diesen Fall gibt es hier nicht.

## Wie es weitergeht

Als Nächstes bauen wir die Sysbox-Sandbox pro Run (eigener Daemon, DDEV inklusive Router) und einen zentralen Ingress mit Auth-Gate, der Preview-URLs in die richtige Sandbox routet. Der nächste Meilenstein: DDEV mit Router in einer Sysbox-Sandbox auf einem echten Linux-Host, erreichbar vom Ingress.

Vielleicht gibt es auch schon den ersten Showcase vom Prototypen.


# Die Docs sind online

Bisher gab es zu Knecht nur diese Updates. Sie erzählen, warum etwas so gebaut ist, aber nicht, wie man es einrichtet. Wer eine Instanz aufsetzen oder einen Workflow bauen wollte, musste sich die Schritte aus mehreren Posts zusammensuchen. Seit dieser Woche gibt es unter [knecht.works/docs](https://knecht.works/docs) eine Dokumentation. Dieser Post zeigt, was drinsteht und was die Seiten außer Text noch können.

## Was drinsteht

Die Docs sind auf Englisch, so wie das Dashboard, damit die Begriffe auf beiden Seiten gleich heißen. Sie bestehen aus drei Teilen.

::card-group
  :::card
  ---
  icon: i-lucide-rocket
  title: Get Started
  to: https://knecht.works/docs/get-started/introduction
  ---
  Was Knecht ist, die Begriffe aus dem Dashboard, Installation, Setup und der laufende Betrieb.
  :::

  :::card
  ---
  icon: i-lucide-workflow
  title: Usage
  to: https://knecht.works/docs/usage/projects
  ---
  Projekte, Workflows, Trigger und der AI Agent, also die Dinge, mit denen man täglich arbeitet.
  :::

  :::card
  ---
  icon: i-lucide-life-buoy
  title: Resources
  to: https://knecht.works/docs/resources/beta-testers
  ---
  Die Seite für Beta-Tester und ein Troubleshooting je Framework.
  :::
::

Vieles davon ist noch nicht sehr detailliert. Die Docs wachsen nach und nach mit dem Produkt. Knecht selbst hat noch einige Ecken und Kanten, und die polieren wir zuerst aus, bevor wir sie ausführlich dokumentieren. Sonst müssten wir die Seiten kurz darauf wieder umschreiben.

## Features

### Suche

Oben rechts sitzt eine Suche, die auch über :kbd{value="meta"} :kbd{value="K"} aufgeht. Sie durchsucht alle Docs-Seiten bis auf Abschnittsebene, ein Treffer springt also direkt zur passenden Überschrift.

![Die Docs-Suche über der Seite "Introduction", die Treffer gruppiert nach Get Started, Usage und Resources](https://knecht.works/assets/docs-search.png)

### Frag Knecht

Neben der Suche gibt es den Button "Frag Knecht", der auch auf :kbd{value="meta"} :kbd{value="I"} hört. Er öffnet ein Chat-Fenster, in dem man Fragen in ganzen Sätzen stellt, auf Deutsch oder Englisch. Der Assistent antwortet aus dem Inhalt der Website, also aus den Docs und diesen Updates, und verlinkt die Seite, auf der die Antwort steht. Was auf der Website nicht steht, weiß er nicht, und das sagt er dann auch.

![Das Panel "Frag Knecht" rechts neben den Docs, mit der Frage nach der Installation und einer Antwort mit Anforderungen und dem Install-Befehl](https://knecht.works/assets/docs-ai.png)

Öffnet man das Fenster auf einer Docs-Seite, bekommt der Assistent diese Seite als Kontext mit und bevorzugt sie bei der Antwort. Das lässt sich im Fenster abschalten. Dahinter läuft ein Claude-Modell, das bei jeder Frage den kompletten Inhalt der Website mitbekommt. Knecht speichert die Chats nicht.

### Docs als Markdown

Jede Docs-Seite gibt es auch als reines Markdown. Der Button "Copy page" oben auf der Seite kopiert den Text in die Zwischenablage. Das Menü daneben bietet den Markdown-Link, die Rohansicht und die Möglichkeit, die Seite direkt in ChatGPT oder Claude zu öffnen. Wer Knecht mit einem Coding-Agenten einrichtet, gibt ihm so die passende Seite mit, ohne HTML drumherum.

::tip
Für alles auf einmal gibt es [llms.txt](https://knecht.works/llms.txt) mit der Übersicht und [llms-full.txt](https://knecht.works/llms-full.txt) mit dem kompletten Inhalt der Website in einer Datei.
::

### Feedback pro Seite

Auf jeder Docs-Seite kann man uns direkt sagen, ob sie geholfen hat und was fehlt.

- Am Ende jeder Seite steht die Frage "Was this page helpful?" mit Daumen hoch und Daumen runter. Ein Klick genügt, wir sehen pro Seite, wie oft welche Antwort kam.
- "Provide Feedback" öffnet ein GitHub-Issue im [Repo der Website](https://github.com/knecht-works/knecht-www){rel="&#x22;nofollow&#x22;"}, mit dem Seitentitel schon im Betreff. Das Repo ist öffentlich, ein Tippfehler lässt sich also auch direkt als Pull Request korrigieren.

### Shortcuts

Suche und "Frag Knecht" lassen sich komplett über die Tastatur bedienen.

| Shortcut                           | Aktion                                         |
| ---------------------------------- | ---------------------------------------------- |
| :kbd{value="meta"} :kbd{value="K"} | Suche öffnen                                   |
| :kbd{value="meta"} :kbd{value="I"} | "Frag Knecht" öffnen und schließen             |
| :kbd{value="meta"} :kbd{value="O"} | Neuen Chat starten                             |
| :kbd{value="tab"}                  | Aktuelle Seite als Kontext an- oder abschalten |

## Ecken und Kanten

Die Docs sind neu, und wir haben sie als die Leute geschrieben, die Knecht am besten kennen. Was für uns offensichtlich ist, fehlt vielleicht genau denen, die es zum ersten Mal einrichten. Uns interessiert deshalb vor allem, wo ihr hängen geblieben seid. Welche Seite hat eine Frage offen gelassen, welcher Begriff ist unerklärt, welches Setup hat nicht funktioniert wie beschrieben. Kleine Hinweise sind dabei oft die nützlichsten.

## Discord

Für alles, was kein Issue ist, gibt es seit Kurzem einen Discord-Server. Dort beantworten wir Fragen zum Setup, diskutieren Workflow-Ideen und zeigen, woran wir gerade bauen. Wer Knecht ausprobiert oder es vorhat, ist dort willkommen, auch ohne konkrete Frage.

::callout
---
color: primary
icon: i-simple-icons-discord
target: _blank
to: https://discord.gg/WuxjmtgUyX
---
Dem Knecht-Discord beitreten
::


# GitHub Auth Evolution

Der GitHub-Login funktionierte vom ersten Tag an. Trotzdem haben wir ihn dreimal umgebaut.

Der Grund: Hinter "mit GitHub verbinden" stecken drei getrennte Fragen, die gerne vermischt werden. Wer sitzt vor dem Dashboard? Womit klont der Server Repos und öffnet PRs? Und wer darf diese Instanz überhaupt benutzen? Am Anfang haben wir alle drei mit einem einzigen Token beantwortet. Hier der Weg von dort bis zum heutigen Stand, inklusive der GitHub-Eigenheiten, über die wir dabei gestolpert sind.

## Was ist eigentlich eine OAuth App?

Eine OAuth App ist der klassische "Sign in with GitHub"-Button. Der User wird zu GitHub geschickt, bestätigt dort den Zugriff und kommt mit einem Access Token zurück. Was dieser Token darf, bestimmen die [Scopes](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/scopes-for-oauth-apps){rel="&#x22;nofollow&#x22;"}, die die App anfragt. `read:user` heißt: nur das Profil lesen. `repo` heißt: voller Lese- und Schreibzugriff auf **alle** Repos, die der User erreichen kann.

Und genau da fing unser Problem an.

## Stufe 1: Ein Token für alles

Die erste Version von Knecht war eine OAuth App mit `repo`-Scope. Der Token, der den Login bestätigt hat, war gleichzeitig das Credential für alle Git-Operationen. Kein zweites Secret, nichts einzurichten. Praktisch, aber zweifach falsch:

- **Der Scope ist zu grob.** Ein `repo`-Token kann alles, was der User kann. In jedem seiner Repos, nicht nur in den Projekten, die Knecht betreut. Feiner geht es bei OAuth-Scopes nicht.
- **Das Credential hängt an einer Person.** Rotiert der User seinen Token oder verlässt die Agentur, kommt der Server an kein Repo mehr. Server-Infrastruktur, die auf dem Account eines Mitarbeiters steht, ist eine tickende Uhr.

## Was eine GitHub App anders macht

Für Stufe 2 haben wir den Repo-Zugriff auf eine **GitHub App** umgestellt. Der [Unterschied zur OAuth App](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/differences-between-github-apps-and-oauth-apps){rel="&#x22;nofollow&#x22;"} ist grundlegend:

- Eine GitHub App ist ein **eigener Akteur** mit eigener Identität, nicht ein User, der seine Rechte verleiht.
- Sie wird auf ausgewählten Repos **installiert**. Der Zugriff ist auf genau diese Repos begrenzt.
- Sie authentifiziert sich mit ihrem **Private Key** und erzeugt daraus [Installation Tokens](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-an-installation-access-token-for-a-github-app){rel="&#x22;nofollow&#x22;"}: gültig für etwa eine Stunde, gescoped auf die installierten Repos. Läuft einer ab, wird einfach der nächste erzeugt.

Der Login blieb OAuth, aber mit geschrumpftem Scope: `read:user`. Der Token wird einmal benutzt, um das Profil zu laden, und danach verworfen. Er wird nie gespeichert. Identität und Repo-Zugriff waren damit sauber getrennt.

Nur das Setup war eine Zumutung. Der Betreiber musste eine OAuth App **und** eine GitHub App von Hand anlegen, vier Secrets in die `.env` kopieren, den Private Key base64-encoden und Callback-URLs eintragen. Bevor irgendetwas lief.

## Stufe 3: Der Manifest Flow

Dann fiel uns auf: Eine GitHub App bringt ihren eigenen OAuth-Client schon mit. Eine einzige App kann also beides, Login und Repo-Zugriff. Die separate OAuth App war überflüssig.

Und GitHub hat für genau diesen Fall den [App Manifest Flow](https://docs.github.com/en/apps/sharing-github-apps/registering-a-github-app-from-a-manifest){rel="&#x22;nofollow&#x22;"}: Eine Software beschreibt die gewünschte App als JSON (Name, Callback-URLs, Permissions), schickt das an GitHub, GitHub legt die App an und gibt **alle** Credentials zurück.

Bei Knecht sieht das so aus: Beim ersten Start zeigt das Dashboard einen Button. Ein Klick, GitHub erstellt die App, Knecht speichert die Credentials verschlüsselt in der eigenen Datenbank. AES-256-GCM, der Schlüssel wird per [HKDF](https://datatracker.ietf.org/doc/html/rfc5869){rel="&#x22;nofollow&#x22;"} aus dem Session-Passwort abgeleitet, das ohnehin gesetzt sein muss. Die Verschlüsselung kostet also keine neue Env-Variable.

Übrig bleiben genau zwei Dinge, die der Betreiber liefert: das Session-Passwort und die Base URL.

Ein Trade-off gehört dazu: Wer das Session-Passwort rotiert, macht die gespeicherten Credentials unlesbar. Die Lösung ist dann nicht Entschlüsseln, sondern das Setup einmal neu durchlaufen.

## Stufe 4: Wer darf überhaupt rein?

Ein Loch blieb bis zuletzt offen: Der Login prüfte **Identität**, aber keine **Erlaubnis**. Jeder GitHub-Account, der den OAuth-Flow abschließt, bekam eine Session.

Ob das ausnutzbar ist, hängt an einer GitHub-Eigenheit, die man einmal verstanden haben muss. Eine App ist entweder [privat oder öffentlich](https://docs.github.com/en/apps/creating-github-apps/setting-up-a-github-app/making-a-github-app-public-or-private){rel="&#x22;nofollow&#x22;"}:

- Eine **private** GitHub App zeigt die Authorize-Seite nur ihrem Besitzer (oder Mitgliedern der besitzenden Org). Alle anderen sehen einen 404. Das wirkt wie eingebaute Zugriffskontrolle, macht aber das Einladen externer Teammitglieder unmöglich. Sie kommen nicht einmal bis zur Zustimmungsseite.
- Eine **öffentliche** App lässt jeden GitHub-User durch den Identity-Flow. Nur so lassen sich beliebige Teammitglieder onboarden. Dafür gated GitHub dann gar nichts mehr.

::callout{color="primary" icon="i-lucide-lightbulb"}
Die Sichtbarkeit einer GitHub App ist keine Zugriffskontrolle. Privat sperrt die Falschen aus, öffentlich lässt alle rein. Wer entscheiden will, wer sich einloggen darf, muss das selbst tun.
::

Also ist Knechts App öffentlich, und die Erlaubnis liegt bei Knecht selbst: eine **Allowlist**. Eine simple Members-Tabelle mit GitHub-Logins. Beim Setup wird der Ersteller automatisch als Owner eingetragen, alle weiteren werden über die Settings eingeladen. Wer nicht auf der Liste steht, wird nach dem GitHub-Login abgewiesen.

"Öffentlich" heißt übrigens nur, dass Fremde die App auf ihren eigenen Repos installieren könnten. Das ist harmlos: Knecht benutzt ausschließlich Installationen, von denen er weiß.

Ein Detail noch, weil es oft übersehen wird: Eine Session ist typischerweise ein Cookie, das bis zu seinem Ablauf gültig bleibt. Wer nur beim Login prüft, hat entfernte Mitglieder also noch tagelang im System, die [OWASP nennt das fehlende serverseitige Invalidierung](https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html){rel="&#x22;nofollow&#x22;"}. Knecht prüft die Mitgliedschaft deshalb bei **jedem** Request neu. Wird jemand entfernt, ist er beim nächsten Klick draußen.

## Was noch fehlt

Rollen. Aktuell hat jedes Mitglied vollen Zugriff, inklusive Einladen. Für die kleinen Teams, für die Knecht gerade gebaut wird, reicht das. Feinere Rechte kommen, wenn echte Rollen gebraucht werden.


# Eine Schnittstelle für alle Integrationen

::note
Dieser Post ist ein Blick unter die Haube. Er erklärt, wie die Integrationen im Server aufgebaut sind, nicht was man damit macht. Was Knecht macht, steht auf der [Startseite](https://knecht.works), wie er auf GitHub und in Jira arbeitet, in [Knecht antwortet jetzt auf GitHub](https://knecht.works/updates/sessions-and-mentions). Die Einrichtung steht in den Docs zu [GitHub](https://knecht.works/docs/integrations/github) und [Jira](https://knecht.works/docs/integrations/jira).
::

Knecht hat mit einer Integration angefangen, GitHub. Dann kam Jira, und Jira funktioniert anders. Es gibt Tickets statt Pull Requests und [Status-Kategorien](https://support.atlassian.com/jira-cloud-administration/docs/what-are-issue-statuses-priorities-and-resolutions/){rel="&#x22;nofollow&#x22;"} statt offen und geschlossen. Ein Ticket kann keinen Pull Request anzeigen, also schreibt Knecht das Ergebnis als Kommentar zurück. Jira bekam deshalb eigenen Code. Jeder weitere Issue-Tracker hätte diesen Code noch einmal bekommen. Dieser Post erzählt, wie wir daraus eine gemeinsame Schnittstelle gemacht haben.

So sieht das Ergebnis in Jira aus. Ein Ticket bekommt ein Label, Knecht nimmt es sich, arbeitet in seiner Umgebung und meldet sich mit einem Pull Request und einem Kommentar zurück.

:update-youtube{#9FFm1AlmRn4 caption="Ein Jira-Ticket bekommt ein Label, Knecht arbeitet und meldet sich mit PR und Kommentar zurück" title="Knecht Works on Jira"}

## Das Problem

### Kopierte Infrastruktur

Jedes Tool braucht dieselben vier Dinge. Knecht muss Zugangsdaten speichern, die Verbindung in den Settings anzeigen, Labels und Status für das Trigger-Formular laden und Webhooks empfangen. Ein [Webhook](https://docs.github.com/en/webhooks/about-webhooks){rel="&#x22;nofollow&#x22;"} ist die HTTP-Anfrage, mit der das Tool Knecht über eine Änderung informiert. Jira hatte dafür eigene API-Routen, eine eigene Datenbanktabelle und ein eigenes Settings-Panel. Ein zweiter Tracker hätte all das kopiert und nur Feldnamen und Texte ausgetauscht.

### Tool-Namen im Code

Schlecht war, dass der Rest von Knecht die Tools beim Namen kannte. Überall, wo eine Integration eine Rolle spielte, stand eine Abfrage wie diese:

```ts
if (tool === 'jira') {
  await postResultComment(ticket)
}
```

Der Code, der einen Run abschließt, wusste, dass Jira einen Ergebnis-Kommentar braucht. Die Behandlung von Mentions kannte nur GitHub. Für jedes neue Tool hätten wir all diese Stellen finden und erweitern müssen.

## Die Schnittstelle

### Fähigkeiten statt Namen

Jetzt ist eine Integration ein Objekt, das eine feste [TypeScript-Schnittstelle](https://www.typescriptlang.org/docs/handbook/2/objects.html){rel="&#x22;nofollow&#x22;"} erfüllt. Der Rest von Knecht fragt nicht mehr, welches Tool er vor sich hat, sondern was es kann. Wer Design Patterns kennt, erkennt darin einen [Adapter](https://refactoring.guru/design-patterns/adapter){rel="&#x22;nofollow&#x22;"}. Stark vereinfacht sieht die Schnittstelle so aus:

```ts
interface Integration {
  webhook: {
    verify(request): boolean
    parse(request): Delivery
  }
  comment(ticket, text): Promise<void>
  labels?: { list(ticket), apply(ticket, names) }
  statuses?: { list(ticket), move(ticket, status) }
  assignee?: { take(ticket), handBack(ticket, person) }
}
```

`verify` prüft die [Signatur](https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries){rel="&#x22;nofollow&#x22;"} eines Webhooks, also ob er wirklich vom Tool kommt. `parse` übersetzt ihn in eine Form, die Knecht versteht. Kommentieren kann jedes Tool, alles mit Fragezeichen ist [optional](https://www.typescriptlang.org/docs/handbook/2/objects.html#optional-properties){rel="&#x22;nofollow&#x22;"}. Aus der Abfrage oben wird damit:

```ts
if (integration.labels) {
  await integration.labels.apply(ticket, ['bug'])
}
```

### Ein Weg für jeden Webhook

`parse` liefert für jedes Tool dieselbe Form zurück. Ein Webhook kann einen Kommentar enthalten, der Knecht direkt anspricht (eine [Mention](https://knecht.works/updates/sessions-and-mentions)), eine Statusänderung am Ticket oder ein Ereignis, auf das ein [Trigger](https://knecht.works/docs/usage/triggers) reagiert. Ein Trigger ist die Regel, die einen Workflow startet. Oft steckt mehreres in einem Webhook, ein geschlossenes Ticket ist zum Beispiel eine Statusänderung und vielleicht auch ein Trigger-Ereignis. Was Knecht damit macht, steht an genau einer Stelle:

```ts
const delivery = await integration.webhook.parse(request)

if (delivery.comment) handleMention(delivery.comment)
if (delivery.statusChange) syncTicketStatus(delivery.statusChange)
if (delivery.event) startMatchingWorkflows(delivery.event)
```

Die Integration muss nur wissen, wie ihr Tool Daten schickt. Was daraus folgt, entscheidet Knecht für alle Tools gleich. Die Idee dahinter beschreibt Alexis King in [Parse, don't validate](https://lexi-lambda.github.io/blog/2019/11/05/parse-don-t-validate/){rel="&#x22;nofollow&#x22;"}: Fremde Daten werden einmal an der Grenze in einen eigenen Typ übersetzt, danach arbeitet der Code nur noch mit diesem Typ.

## Unterschiede als Daten

Was sich zwischen zwei Tools noch unterscheidet, sind vor allem Begriffe und Formate. Ein Ticket heißt anders, andere Status gelten als erledigt, der Titel steht an einer anderen Stelle im Payload. Das beschreibt jede Integration als Daten, die Logik dazu gibt es nur einmal.

### Der Tracker

Ein Tracker ist ein Tool, in dem ein Team seine Tickets verwaltet, etwa Jira. Was Knecht über ihn wissen muss, passt in eine kurze Beschreibung:

```ts
const jira = {
  noun: 'ticket',
  statusGroups: { new: 'To Do', indeterminate: 'In Progress', done: 'Done' },
  closedGroups: ['done'],

  toTicket: issue => ({
    title: issue.fields.summary,
    body: adfToMarkdown(issue.fields.description),
    status: issue.fields.status.name,
    labels: issue.fields.labels,
  }),
}
```

Der obere Teil sind die Begriffe des Tools, also wie ein Ticket heißt, welche Status-Kategorien es gibt und welche davon als erledigt gelten. `toTicket` übersetzt die Daten aus dem Webhook in ein einheitliches Ticket. Ab da entscheidet für alle Tracker derselbe Code, ob ein Trigger startet, und auch der Text, den der [Agent](https://knecht.works/docs/usage/agent) über das Ticket liest, entsteht daraus.

### Das Trigger-Formular

Im [Trigger-Dialog](https://knecht.works/docs/usage/triggers) wählt man, bei welchem Ereignis ein Workflow startet. Welche Ereignisse es gibt, beschreibt jede Integration selbst:

```ts
trigger: {
  form: {
    events: [
      { label: 'Label added', options: 'labels' },
      { label: 'Status reached', options: 'statuses' },
    ],
  },
  options: {
    labels: () => jira.get('/label'),
    statuses: () => jira.get('/status'),
  },
}
```

Aus `form` baut Knecht den Dialog. `options` füllt die Auswahlfelder mit den Labels und Status, die es in Jira wirklich gibt. `form` sind reine Daten und gehen in den Browser, `options` läuft auf dem Server, weil nur der die Zugangsdaten hat.

### Die Verbindung

Die Verbindung sind die Zugangsdaten, mit denen Knecht im Tool liest und schreibt, bei Jira etwa die Site-URL, eine E-Mail und ein API-Token. Ein Admin trägt sie einmal in den Settings ein, danach gilt die Verbindung für die ganze Instanz. Auch dieses Formular ist eine Beschreibung. Die Integration sagt nur, welche Felder sie braucht und wie sie prüft, ob die Zugangsdaten stimmen:

```ts
connection: {
  fields: [
    { key: 'siteUrl', label: 'Site URL', type: 'url' },
    { key: 'email', label: 'Email', type: 'email' },
    { key: 'apiToken', label: 'API token', type: 'secret' },
  ],
  verify: values => jira.whoAmI(values),
}
```

Eine gemeinsame Vue-Komponente baut daraus das Formular, eine gemeinsame API-Route speichert es. Der Feldtyp bringt die Regeln mit. Eine `url` muss mit https beginnen, ein `secret` wird [verschlüsselt gespeichert](https://cheatsheetseries.owasp.org/cheatsheets/Cryptographic_Storage_Cheat_Sheet.html){rel="&#x22;nofollow&#x22;"} und nur als Vorschau angezeigt. Vor dem Speichern meldet sich `verify` einmal beim Tool an, damit falsche Zugangsdaten gar nicht erst gespeichert werden.

## Tests gegen die Schnittstelle

### Vom Durchklicken zu Fixtures

Am Anfang haben wir Trigger von Hand getestet. Die lokale Knecht-Instanz war über einen [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/networks/connectors/cloudflare-tunnel/){rel="&#x22;nofollow&#x22;"} erreichbar, wir haben in Jira ein Ticket angelegt, ein Label gesetzt, den Status verschoben und im Log nachgesehen, ob der richtige Workflow startet. Das dauerte, und nach jeder Änderung an der Trigger-Logik ging es von vorne los.

Deshalb schreibt Knecht jetzt auf Wunsch jeden geprüften Webhook als JSON-Datei in einen Ordner. Eine Runde Durchklicken im Tool reicht, und die aufgezeichneten Webhooks werden zu Fixtures. Stand September 2026 sind es 89. Die Tests spielen sie erneut ab und legen für jeden Trigger fest, bei welchen Webhooks er feuern muss und bei welchen nicht:

```ts
const cases = [
  { trigger: 'Label "bug" added', firesOn: ['ticket-labeled-bug'] },
  { trigger: 'Status "Done" reached', firesOn: ['ticket-moved-to-done'] },
]

for (const { trigger, firesOn } of cases) {
  for (const webhook of recordedWebhooks) {
    expect(fires(trigger, webhook)).toBe(firesOn.includes(webhook.name))
  }
}
```

Steht die Verbindung zu einem Tool einmal und ist eine Runde Webhooks aufgezeichnet, wissen wir nach jeder Änderung in Sekunden, ob die Trigger noch stimmen, ohne das Tool zu öffnen. Ändert ein Tool sein Format, zeichnen wir neu auf und sehen im Test sofort, was sich geändert hat.

### Eine Suite für alle

Die Fixtures prüfen, ob Trigger richtig entscheiden. Ob eine Integration die Schnittstelle überhaupt richtig erfüllt, prüft eine zweite Ebene. Weil alle Integrationen dieselbe Schnittstelle haben, laufen sie durch dieselbe Test-Suite in [Vitest](https://vitest.dev/guide/){rel="&#x22;nofollow&#x22;"}. Eine Integration liefert dafür nur Bausteine, die Webhooks in ihrem Format erzeugen:

```ts
webhookSuite({
  integration: jira,
  created: project => jiraWebhook('issue_created', project),
  labeled: project => jiraWebhook('issue_updated', project, { labels: ['bug'] }),
  mention: project => jiraComment(project, '@Knecht bitte anschauen'),
})
```

Die Suite schickt diese Webhooks durch die echte Route und erwartet von jeder Integration dasselbe Verhalten.

Martin Fowler nennt so etwas einen [Contract Test](https://martinfowler.com/bliki/ContractTest.html){rel="&#x22;nofollow&#x22;"}. Für eine neue Integration heißt das, dass wir nicht überlegen müssen, was zu testen ist. Sobald sie die Bausteine liefert und die Suite grün ist, verhält sie sich wie die anderen.

## Was wir mitnehmen

Eine neue Integration besteht jetzt aus der Beschreibung des Trackers, den API-Aufrufen und dem Verbindungsformular. Trigger, Mentions, Kommentare, Labels, Status und das Settings-Panel kommen mit der Schnittstelle. Wer so etwas selbst baut, kann sich an vier Punkten orientieren:

- Der Rest der Anwendung fragt nach Fähigkeiten, nie nach dem Namen des Tools.
- Eingehende Daten werden an der Grenze in eine gemeinsame Form übersetzt. Danach gibt es keinen Tool-spezifischen Code mehr. Microsoft beschreibt das Muster als [Anti-Corruption Layer](https://learn.microsoft.com/en-us/azure/architecture/patterns/anti-corruption-layer){rel="&#x22;nofollow&#x22;"}.
- Was sich nur in Daten unterscheidet, etwa Formulare oder Begriffe, wird als Daten beschrieben und nicht als Code.
- Getestet wird gegen die Schnittstelle, damit jede Integration dieselben Tests bestehen muss.


# Landingpage ist Online

Die Landingpage ist online, und das ganz bewusst, bevor überhaupt noch der Prototyp steht.

::callout{color="primary" icon="i-lucide-mouse"}
Schon auf den Knecht geklickt?
::

## Warum die Seite

Ein Produkt komplett fertig zu bauen und dann zu hoffen, dass es jemand braucht, ist riskant. Deshalb steht die Landingpage am Anfang. Sie macht drei Dinge:

- Sie erklärt die Idee in wenigen Sätzen.
- Sie sammelt die ersten Beta-Tester.
- Sie macht den Weg öffentlich, damit Feedback früh kommt und nicht erst zum Launch.

### Sprache

Viele Startups zielen gleich auf den Internationalen Markt ab. Wir finden, dass dies mit der Sprache anfängt. Wir werden uns zuerst auf den DACH Raum konzentrieren. Englisch als zweite Sprache muss daher noch etwas warten.

## Was sie (noch) nicht ist

Damit keine falschen Erwartungen entstehen: Diese Seite ist kein Produkt. Kein Login, keine Demo, nichts zum Ausprobieren. Was du siehst, ist die Idee und ein erster Blick auf die geplante Oberfläche.

## Wie es weitergeht

Als Nächstes steht der Prototyp an: Projekte, Workflows und der AI Agent.

Das Ziel für die nächsten Wochen ist klar: die ersten 3 bis 5 Agenturen als Beta-Tester finden, die Knecht an echten Projekten testen und ehrlich zurückmelden, was funktioniert.

::callout{color="neutral" icon="i-lucide-arrow-right"}
Willst du früh dabei sein? Trag dich als [Beta-Tester](https://knecht.works/#cta) ein.
::


# Langdock als AI-Provider

Der Agent in der [AI-Action](https://knecht.works/updates/workflow-engine) ist [opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"}. Bisher lief er über die Provider von OpenCode selbst, also Zen oder Go, mit einem Key aus der OpenCode-Konsole. Jetzt haben wir Langdock als Provider dazu gebaut, eine europäische Alternative. Ein API-Key deckt auch hier die Modelle mehrerer Anbieter ab, aber jede Anfrage des Agenten bleibt in der gewählten Region.

## Was Langdock ist

[Langdock](https://langdock.com){rel="&#x22;nofollow&#x22;"} ist ein AI-Gateway für europäische Firmen. Es sitzt vor mehreren Modell-Anbietern, darunter OpenAI, Anthropic, Google, Meta und Mistral. Das Team schließt einen Vertrag und bekommt einen API-Key, dahinter sind die Modelle aller Anbieter erreichbar.

Der zweite Grund für so ein Gateway ist Data Residency, also die Zusage, dass jede Anfrage in einer festen Region verarbeitet wird, EU oder US. Das betrifft den Agenten direkt, denn seine Prompts enthalten Code und Daten aus dem Kundenprojekt. Viele Kundenverträge schreiben vor, dass solche Daten die EU nicht verlassen. Mit Langdock in der Region EU gilt das auch für die Arbeit des Agenten, und oft ist das die Bedingung, unter der er auf dem Projekt überhaupt eingesetzt werden darf.

## Opencode kennt Langdock nicht

opencode löst Provider über das Register [models.dev](https://models.dev){rel="&#x22;nofollow&#x22;"} auf. Für die bisherigen Provider reicht deshalb eine Umgebungsvariable mit dem API-Key, alles Weitere weiß opencode selbst. Langdock steht in dem Register nicht, dieser Weg fällt also aus.

Stattdessen erzeugt Knecht für jeden Run eine `opencode.json` im Checkout und deklariert Langdock darin als eigenen Provider, mit dem Endpoint der gewählten Region und genau den Modellen, die dieser Run nutzen darf. Gekürzt sieht der Block so aus:

```json
{
  "provider": {
    "langdock": {
      "name": "Langdock",
      "options": {
        "baseURL": "https://api.langdock.com/openai/eu/v1",
        "apiKey": "{env:LANGDOCK_API_KEY}"
      },
      "models": { "gpt-5.5": {} }
    }
  }
}
```

Der Key selbst steht nicht in der Datei. Die Config verweist mit `{env:LANGDOCK_API_KEY}` nur auf eine Umgebungsvariable, und Knecht übergibt den Wert direkt dem opencode-Prozess. Im Checkout, in dem der Agent arbeitet, landet der Key damit nie.

Eine Eigenheit des Gateways steckt noch in der `baseURL`. Langdock spricht je nach Modell eine andere API, Claude-Modelle die Anthropic-kompatible, alle anderen die OpenAI-kompatible. Knecht entscheidet am Modellnamen, unter welchem Endpoint ein Modell in der Config deklariert wird. Im Picker wählt man nur ein Modell, von der Unterscheidung merkt man nichts.

## Die Einrichtung

Alles dazu liegt unter "Settings" → "Agent". Dort wählt man Langdock als Provider, daneben erscheint die Auswahl der Region. Sie gilt für die ganze Instanz, also für jede Anfrage aus jedem Run. Danach speichert man den Langdock-API-Key. Er liegt wie alle Provider-Keys [verschlüsselt](https://knecht.works/updates/gh-auth-evolution) in der Datenbank und lässt sich nachträglich nur ersetzen, nicht wieder auslesen.

![Die Agent-Settings mit Langdock als Provider, der Region-Auswahl und dem geöffneten Modell-Picker](https://knecht.works/assets/settings-agent-langdock.png)

Sobald der Key gespeichert ist, lädt der Modell-Picker die Liste live aus dem Langdock-Workspace. Es erscheinen genau die Modelle, die dort freigeschaltet sind, GPT- und Claude-Modelle im selben Picker. Default-Modell und das optionale Subtask-Modell, das kleinere Modell für Nebenaufgaben des Agenten, funktionieren wie bei jedem anderen Provider.

::note
Beim Wechsel des Providers leert Knecht die gespeicherten Modelle, denn die alten Namen würden im Katalog des neuen Providers nicht auflösen. Die AI-Action läuft erst wieder, wenn ein neues Default-Modell gewählt ist.
::

## Modelle mischen

An der AI-Action selbst ändert sich nichts. Der Agent arbeitet wie gewohnt im laufenden Projekt, liest Code, ändert Dateien und führt Befehle aus, auch mit Reasoning-Modellen wie GPT-5.5. Und weil ein Key alle Modelle des Workspace abdeckt, kann ein Workflow über den Modell-Override pro Schritt weiterhin die Anbieter mischen:

```yaml
steps:
  - type: ai
    id: analyze
    label: Analyze bug
    model: gpt-5.5
    prompt: Stelle den Bug aus {{ inputs.title }} nach und beschreibe die Ursache.
  - type: ai
    id: fix
    label: Fix bug
    model: claude-sonnet-4-5
    prompt: Behebe die Ursache aus {{ steps.analyze.text }}.
```

Beide Schritte laufen über denselben Langdock-Key und in derselben Region. Der Wechsel auf das EU-Gateway kostet an dieser Stelle also nichts, was man von OpenCode Zen gewohnt ist.


# Warum Knecht nicht Open Source ist

Das [Knecht-Repo](https://github.com/knecht-works/knecht-cloud){rel="&#x22;nofollow&#x22;"} war von Anfang an öffentlich auf GitHub, eine Lizenz hatte es aber nie. Das haben wir jetzt geändert: Knecht steht ab sofort unter der Functional Source License, kurz FSL. Hier steht, warum überhaupt eine Lizenz nötig war, warum es kein MIT geworden ist und was du mit dem Code offiziell darfst.

## Ohne Lizenz geht nichts

Öffentlich sichtbar und frei nutzbar sind zwei verschiedene Dinge. Code ist urheberrechtlich geschützt wie ein Text oder ein Foto, und ohne ausdrückliche Lizenz gilt der Standard des Urheberrechts: alle Rechte vorbehalten. [GitHub weist selbst darauf hin](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository){rel="&#x22;nofollow&#x22;"}, dass ein öffentliches Repo ohne Lizenz nur angesehen und auf der Plattform geforkt werden darf. Herunterladen, verändern, produktiv einsetzen: genau genommen alles nicht erlaubt.

Ein Repo ohne Lizenz ist damit restriktiver als jede noch so strenge Lizenz. Absicht war das bei Knecht nicht, wir hatten die Lizenzfrage schlicht noch nicht entschieden. Wer Knecht in der Beta selbst hostet, tat das bisher mit unserer mündlichen, aber nirgends festgehaltenen Erlaubnis.

## Das Dilemma

An die Lizenz hatten wir zwei Anforderungen, die sich auf den ersten Blick widersprechen. Der Code soll öffentlich bleiben, und jeder soll Knecht kostenlos selbst hosten, lesen und anpassen dürfen. Gleichzeitig soll Knecht irgendwann Geld verdienen können, damit das Projekt dauerhaft betrieben werden kann. Wie genau, ist offen. Vielleicht eine gehostete Version, vielleicht bezahlte Zusatzfunktionen für Teams.

Mit einer permissiven Lizenz wie [MIT](https://opensource.org/license/mit){rel="&#x22;nofollow&#x22;"} oder Apache verträgt sich das nicht. Permissiv heißt: jeder darf alles, auch Knecht nehmen und als eigenes bezahltes Produkt anbieten. Elasticsearch hat vorgemacht, wohin das führt. Es war Apache-lizenziert, AWS verkaufte es als eigenen Managed Service, und Elastic ging dabei leer aus. 2021 [wechselte Elastic auf eine restriktivere Lizenz](https://www.elastic.co/blog/licensing-change){rel="&#x22;nofollow&#x22;"}, AWS forkte die letzte freie Version und betreibt sie seitdem als [OpenSearch](https://opensearch.org/){rel="&#x22;nofollow&#x22;"} weiter. Terraform (Fork: [OpenTofu](https://opentofu.org/){rel="&#x22;nofollow&#x22;"}) und Redis (Fork: [Valkey](https://valkey.io/){rel="&#x22;nofollow&#x22;"}) haben denselben Zyklus hinter sich.

Diese Geschichten haben eine Gemeinsamkeit: Der Lizenzwechsel kam spät, als längst eine Community auf der freien Lizenz aufgebaut hatte. Ändern lässt sich eine Lizenz nämlich nur für neue Versionen. Was einmal permissiv veröffentlicht ist, bleibt es für immer, und beim Wechsel steht die Community verständlicherweise auf der Seite des Forks. Wenn eine Grenze nötig ist, dann ehrlicherweise von Anfang an.

## Die Kandidaten

Ernsthaft angeschaut haben wir uns fünf Lizenzen:

| Lizenz       | Modell                 | Verbietet                                            | Wird Open Source        |
| ------------ | ---------------------- | ---------------------------------------------------- | ----------------------- |
| MIT / Apache | Open Source, permissiv | nichts                                               | ist es schon            |
| AGPL         | Open Source, Copyleft  | nichts, erzwingt aber Offenlegung eigener Änderungen | ist es schon            |
| BSL          | source available       | was der Hersteller selbst festlegt                   | nach bis zu vier Jahren |
| ELv2         | source available       | das Anbieten als Managed Service                     | nie                     |
| FSL          | source available       | Konkurrenzprodukte                                   | nach zwei Jahren        |

Die [AGPL](https://www.gnu.org/licenses/agpl-3.0.html){rel="&#x22;nofollow&#x22;"} ist die eine echte Open-Source-Lizenz, die ein Geschäftsmodell schützt. Wer AGPL-Software als Webdienst betreibt oder in ein Produkt einbaut, muss seinen eigenen Code offenlegen, und das schreckt Konkurrenten zuverlässig ab. Es schreckt aber auch die Falschen ab: Viele Firmen verbieten AGPL-Software pauschal, weil ihre Rechtsabteilung die Offenlegungspflicht nicht im Einzelfall prüfen will. Ausgerechnet Agenturen mit vorsichtigen Kunden, also die Leute, für die Knecht gebaut wird, wären davon betroffen.

BSL, ELv2 und FSL stehen für dasselbe Modell, es nennt sich source available. Der Code ist öffentlich und frei nutzbar, nur die kommerzielle Verwertung bleibt dem Hersteller vorbehalten. Die [BSL](https://mariadb.com/bsl11/){rel="&#x22;nofollow&#x22;"} (von MariaDB) verlangt, dass der Hersteller die erlaubte Nutzung selbst formuliert, deshalb liest sich jede BSL anders und muss einzeln geprüft werden. Selbst ob kostenloses Self-Hosting erlaubt ist, hängt dort vom jeweiligen Hersteller ab. Die [ELv2](https://www.elastic.co/licensing/elastic-license){rel="&#x22;nofollow&#x22;"} (von Elastic) ist einfach, wird aber nie zu Open Source. Die FSL ([von Sentry](https://blog.sentry.io/introducing-the-functional-source-license-freedom-without-free-riding/){rel="&#x22;nofollow&#x22;"}) ist die jüngste der drei: eine Seite Text, feste Regeln und eine eingebaute Umwandlung zu Open Source.

## Was die FSL erlaubt

Für die allermeisten ändert sich durch die Lizenz nichts, sie erlaubt genau das, was Knecht-Nutzer ohnehin tun:

- Knecht selbst hosten und produktiv einsetzen, auch kommerziell, auch für Kundenprojekte
- den Code lesen, verändern und forken
- Dienstleistungen rund um Knecht anbieten, etwa Setup und Betrieb für einen Kunden

Verboten ist eine Sache: Knecht anderen als eigenes kommerzielles Produkt anzubieten, also etwa Knecht-Hosting zu verkaufen oder Knecht unter anderem Namen zu vertreiben. Der [Lizenztext](https://fsl.software/){rel="&#x22;nofollow&#x22;"} nennt das Competing Use.

Und dann ist da die Klausel, wegen der es am Ende die FSL geworden ist: Jede veröffentlichte Version wird zwei Jahre nach ihrem Release automatisch unter die [Apache-2.0-Lizenz](https://www.apache.org/licenses/LICENSE-2.0){rel="&#x22;nofollow&#x22;"} gestellt, also echtes Open Source. Das steht unwiderruflich im Lizenztext, wir könnten es nicht einmal zurücknehmen. Sollte Knecht eines Tages eingestellt werden, ist der komplette Code spätestens zwei Jahre später frei. Niemand baut hier auf etwas, das ihm dauerhaft weggenommen werden kann.

## Kein Open Source

Im Alltag wird jedes öffentliche Repo schnell Open Source genannt. Open Source ist aber ein definierter Begriff: Die [Definition der Open Source Initiative](https://opensource.org/osd){rel="&#x22;nofollow&#x22;"} verlangt unter anderem, dass eine Lizenz kein Einsatzfeld ausschließt, auch nicht das der Konkurrenz. Genau das tut die FSL mit ihrem Competing-Use-Verbot. Knecht ist damit kein Open Source. Die passenden Begriffe sind source available oder [Fair Source](https://fair.io/){rel="&#x22;nofollow&#x22;"}, so heißt die Initiative, unter der Sentry und andere dieses Modell zusammengefasst haben.

## Wie es weitergeht

Ein Punkt steht noch auf der Liste: Bevor der erste externe Pull Request gemergt wird, richten wir ein CLA ein, ein [Contributor License Agreement](https://de.wikipedia.org/wiki/Contributor_License_Agreement){rel="&#x22;nofollow&#x22;"}. Das ist eine kurze Vereinbarung, mit der Contributors uns die Rechte einräumen, ihren Beitrag zusammen mit dem restlichen Code zu lizenzieren. Ohne sie würden sich die Rechte am Code auf viele Personen verteilen, und jedes spätere Lizenzmodell müsste mit jedem einzelnen Contributor neu verhandelt werden.


# Von 5 Sekunden auf unter 0,5

Am Desktop hat die Landingpage sofort geladen. Am Handy war sie furchtbar langsam, über fünf Sekunden bis sie da war. Schuld war am Ende ein einziger CSS-Effekt: `blur()`. Hier der ganze Weg von der Diagnose bis zu dem, was unter der Haube wirklich passiert.

## Das Problem

Am Handy war die Seite einfach langsam. Das Laden dauerte spürbar lang, am Desktop war es blitzschnell. Die üblichen Verdächtigen, zu große Bilder, zu viel JavaScript, langsamer Server, waren es nicht.

Am Ende war es der Hintergrund. Dort liegen ein paar große, weiche Lichtflecken (Glows), umgesetzt mit `filter: blur()`. Ein Element war über 1000px breit, mit einem Blur-Radius von 100px.

::callout{color="primary" icon="i-lucide-zap-off"}
Über fünf Sekunden bis zum ersten Frame ist für eine Landingpage tödlich. Genau dort entscheidet sich, ob jemand bleibt.
::

## Warum Blur so teuer ist

`blur()` ist eine [Convolution](https://developer.chrome.com/blog/animated-blur){rel="&#x22;nofollow&#x22;"}: Für jeden Output-Pixel werden die umliegenden Input-Pixel gewichtet zusammengerechnet. Die Kosten skalieren mit Fläche **und** Radius, ein `blur(100px)` ist also drastisch teurer als ein `blur(5px)`.

Im Detail läuft pro Frame ungefähr das ab:

::steps{level="3"}
### Render-to-Texture

Das Element wird zuerst in eine eigene Off-Screen-Textur gerendert. Allein das promotet es zu einer eigenen Compositing-Layer und kostet GPU-Speicher.

### Separable Gaussian

Ein 2D-Gaussian lässt sich in zwei 1D-Passes zerlegen (horizontal, dann vertikal). Das senkt die Kosten von O(n²) auf O(n) pro Pixel, ist also schon die optimierte Variante.

### Downsampling

Bei großen Radien rechnet die Engine nicht in voller Auflösung. Skia (Chrome) [skaliert ab einem Sigma > 4 herunter](https://api.skia.org/classSkImageFilters.html){rel=""nofollow""}, blurrt auf der kleineren Buffer-Größe und skaliert wieder hoch.
::

Trotz all dieser Optimierungen bleibt eine riesige Fläche übrig, die vor dem ersten Paint fertig sein muss. Auf dem Desktop fällt das nicht auf. Eine Mobile-GPU stemmt das deutlich langsamer, und genau das hat den ersten Frame um Sekunden verzögert.

## Warum es Mobile-GPUs besonders trifft

Mobile-GPUs arbeiten fast alle [Tile-Based](https://developer.samsung.com/galaxy-gamedev/resources/articles/gpu-framebuffer.html){rel="&#x22;nofollow&#x22;"}: Der Framebuffer wird in kleine Tiles zerlegt, die im schnellen On-Chip-Speicher gerendert werden. Das spart enorm Memory-Bandwidth, funktioniert aber nur, solange ein Tile für sich allein berechenbar ist.

Ein Blur bricht genau diese Annahme. Die Convolution muss Pixel über die Tile-Grenze hinaus lesen. Die GPU kann den Effekt also nicht tile-lokal halten, sondern muss in den langsamen System-Memory schreiben und wieder lesen. Auf Hardware mit ohnehin knapper Fill-Rate und Bandwidth ist das der teuerste Fall.

## `filter` ist nicht `backdrop-filter`

Im Header steckte noch ein zweiter Blur, und der ist eine ganz andere Baustelle. Die beiden werden oft verwechselt:

- **`filter: blur()`** blurrt die **eigenen Pixel** des Elements. Inhalt dahinter ist egal.
- **[`backdrop-filter: blur()`](https://www.w3tweaks.com/css/css-filter-backdrop-filter/){rel="&#x22;nofollow&#x22;"}** blurrt **alles, was dahinter liegt**, und liest diese Pixel bei jedem Frame neu.

Letzteres ist beim Scrollen brutal: Der Backdrop ändert sich ständig, also wird der Blur permanent neu berechnet. [Genau das ruckelt sichtbar](https://github.com/vuejs/vitepress/issues/1049){rel="&#x22;nofollow&#x22;"}, bei älteren Firefox-Builds unter Linux. Ein fixer, halbtransparenter Header mit `backdrop-filter` ist einer der häufigsten Jank-Verursacher überhaupt.

## Und Blur animieren?

Kurz: nicht den Radius animieren. Jeder Frame triggert die volle Convolution auf der GPU und sprengt das 16ms-Frame-Budget, das Ergebnis liegt weit unter 60fps.

Der [Trick von Chrome](https://developer.chrome.com/blog/animated-blur){rel="&#x22;nofollow&#x22;"}: ein paar vorberechnete Kopien mit exponentiell steigendem Blur stapeln und per `opacity` zwischen ihnen cross-faden. Opacity ist compositor-only und damit billig. Man animiert also nicht den Blur, sondern täuscht ihn vor.

## Die Lösung

Im konkreten Fall war sie fast enttäuschend simpel: den Blur ganz weglassen.

Statt einen scharfen Kreis teuer zu blurren, sind die Glows jetzt mehrstufige Radial-Gradients, die von Haus aus weich sind. Optisch praktisch identisch, aber ohne Filter, ohne extra Layer, ohne Convolution. Den `backdrop-filter` im Header habe ich gleich mit rausgeworfen.

Andere valide Wege, je nach Fall: ein vorgeblurtes Bild als Asset ausliefern, den Radius klein halten, oder bewusst auf einem kleineren Element blurren.

Das Ergebnis: Statt über fünf Sekunden ist die Seite jetzt in unter einer halben Sekunde da. Zehnmal schneller, ohne dass man dem Design den Unterschied ansieht.

## Wie man so etwas findet

In den Chrome DevTools führt der [Rendering-Tab](https://developer.chrome.com/docs/devtools/rendering/performance){rel="&#x22;nofollow&#x22;"} schnell zur Ursache:

- **Paint Flashing** zeigt grün, was neu gezeichnet wird. Ein Header, der beim Scrollen dauergrün blinkt, ist ein eindeutiges Signal.
- **Layer Borders** und der **Layers-Tab** zeigen, welche Elemente eine eigene Compositing-Layer bekommen, dort taucht jeder Blur auf.
- Im **Performance-Panel** sieht man die langen Paint- und GPU-Tasks direkt im Flame-Chart.

## Was ältere Browser damit zu tun haben

Mein erster Reflex war: "Blur wird doch überall unterstützt." Stimmt laut Caniuse, sagt aber nichts über Performance.

**GPU-Beschleunigung kann ganz wegfallen.** Firefox rendert über WebRender, fällt aber auf vielen Linux-Setups (alte Intel-GPUs, proprietäre Nvidia-Treiber) auf [Software-Rendering](https://wiki.archlinux.org/title/Firefox/Tweaks){rel="&#x22;nofollow&#x22;"} zurück. Dann läuft die Blur-Convolution auf der CPU, und aus "unmerklich" wird "ruckelt".

::callout{color="primary" icon="i-lucide-lightbulb"}
Ein grüner Caniuse-Balken heißt "der Browser kennt das Feature", nicht "er macht es schnell, auch ohne GPU-Beschleunigung".
::

## Was ich mitnehme

Der schönste Effekt taugt nichts, wenn die Seite dadurch langsam wird. Blur ist teuer in der Berechnung, Layer-erzeugend, mit Nebenwirkungen auf Stacking und Positionierung, und besonders fragil auf Mobile und ohne GPU-Beschleunigung. Und immer auf echten, eher schwachen Geräten testen, nicht nur auf der dicken Entwickler-Maschine.


# Jedes Repo bootet, auch ohne DDEV-Config

Bisher brauchte ein Repo eine `.ddev/config.yaml`, sonst konnte Knecht es nicht booten. Seit Version 0.10 baut Knecht die Umgebung aus den Dateien im Repo, wenn keine Config da ist. Ein Dev-Server wird dabei zur Live-Preview, [Hot Reload](https://vite.dev/guide/features.html#hot-module-replacement){rel="&#x22;nofollow&#x22;"} eingeschlossen. Dieser Post erklärt, was Knecht erkennt, wie die Preview durchkommt und was wir dabei über [DDEV](https://ddev.com/){rel="&#x22;nofollow&#x22;"}, [Docker Compose](https://docs.docker.com/compose/){rel="&#x22;nofollow&#x22;"} und [Nuxt](https://nuxt.com/){rel="&#x22;nofollow&#x22;"} gelernt haben.

## Was Knecht erkennt

Beim Start jedes Runs liest Knecht die Dateien aus dem Checkout, die die Versionen ohnehin festlegen:

|                 | Quelle                                                                | Regel                                                           |
| --------------- | --------------------------------------------------------------------- | --------------------------------------------------------------- |
| PHP             | `require.php` in `composer.json`                                      | die höchste Version des DDEV-Images, die den Constraint erfüllt |
| Node            | `mise.toml`, `.mise.toml`, `.tool-versions`, `.nvmrc`, `engines.node` | die erste Datei mit einem Wert gewinnt                          |
| Package Manager | Feld `packageManager`, sonst das Lockfile                             | npm, pnpm, yarn oder bun                                        |

Fehlt eine Angabe, gilt der DDEV-Default. Das Run-Log nennt jeden Wert mit seiner Quelle, etwa `PHP 8.2 from composer.json, Node 22 from .nvmrc`.

### Die generierte Config

Aus den Werten schreibt Knecht eine `.ddev/config.yaml` in den Checkout. Für ein Nuxt-Repo, das Node 22 pinnt und keine `composer.json` hat, sieht sie so aus:

```yaml
#knecht-generated
name: knecht-run-42
type: php
docroot: ""
webserver_type: generic
php_version: "8.4"
nodejs_version: "22"
omit_containers:
  - db
corepack_enable: true
disable_settings_management: true
```

Der Projekttyp ist `php`, weil DDEV dafür keine CMS-Annahmen trifft. Der Web-Server ist [`generic`](https://docs.ddev.com/en/stable/users/configuration/config/#webserver_type){rel="&#x22;nofollow&#x22;"}, also laufen weder nginx noch php-fpm, denn ohne Website gibt es nichts auszuliefern. Der Datenbank-Container fehlt, Corepack ist eingeschaltet, und DDEV schreibt keine Settings-Dateien ins Repo. Ports, Umgebungsvariablen und Daemons legt Knecht wie bei jedem Projekt in eigenen Override-Dateien daneben ab, dazu weiter unten mehr.

Den Kommentar in der ersten Zeile braucht Knecht, damit es bei jedem weiteren Run sicher sagen kann, dass es sich um ein Projekt ohne eigene DDEV-Config handelt, obwohl im Checkout jetzt eine liegt.

Der Marker sorgt auch dafür, dass nichts davon in einem Commit landet. Die Git-Actions im Run committen alles, was im Checkout liegt. Deshalb schreibt Knecht vor dem ersten Run das Verzeichnis `.ddev/` in die Datei [`.git/info/exclude`](https://git-scm.com/docs/gitignore){rel="&#x22;nofollow&#x22;"} des Clones. Das ist eine Ignore-Liste, die nur in diesem Clone gilt und selbst nicht im Repo liegt, Git behandelt die Einträge wie eine `.gitignore`. Bei einem Repo mit eigener Config stehen dort nur Knechts eigene Dateien, bei einer generierten das ganze Verzeichnis, weil auch DDEV beim Start Dateien hineinlegt. Welcher Fall gilt, liest Knecht am Marker ab.

### Package Manager

npm steckt im DDEV-Image und ist der Default, wenn das Repo nichts anderes festlegt. [Corepack](https://nodejs.org/api/corepack.html){rel="&#x22;nofollow&#x22;"} ist in jeder generierten Umgebung eingeschaltet, damit pnpm und yarn ohne Installation laufen. Corepack lädt die Version aus dem Feld `packageManager`, im Repo muss nichts installiert werden.

[bun](https://bun.sh/){rel="&#x22;nofollow&#x22;"} fehlt im Image. Knecht ergänzt den Image-Build um eine Zeile, die bun über npm installiert. Die Schicht bleibt im [Docker-Cache](https://docs.docker.com/build/cache/){rel="&#x22;nofollow&#x22;"}, nur die erste bun-Session auf einem Server baut sie.

Die Downloads aller vier landen im serverweiten Cache von DDEV. Composer, npm und Corepack zeigt DDEV selbst dorthin, die Pfade für den pnpm-Store, yarn und bun setzt Knecht dazu, und zwar für jedes Projekt, auch für eines mit eigener DDEV-Config. Ein Server lädt jedes Paket einmal, spätere Sessions installieren aus dem Cache.

### Node-Version

Konkrete Versionen wie `22` oder `v20.11` übernimmt Knecht bis zur Minor-Version, [nvm](https://github.com/nvm-sh/nvm#nvmrc){rel="&#x22;nofollow&#x22;"}-Codenamen wie `lts/iron` als Major-Version. Bewegliche Ziele wie `lts/*` oder `latest` pinnt Knecht nicht, dann gilt der Default, mit einer Warnung im Run-Log. [`engines.node`](https://docs.npmjs.com/cli/v10/configuring-npm/package-json#engines){rel="&#x22;nofollow&#x22;"} in der `package.json` ist meist ein Bereich wie `>=20`. Erfüllt der DDEV-Default den Bereich, bleibt er, sonst nimmt Knecht die höchste LTS-Version, die passt.

### PHP-Version

Zur Wahl stehen die Versionen des DDEV-Images, derzeit 5.6 bis 8.4. Composer-[Constraints](https://getcomposer.org/doc/articles/versions.md){rel="&#x22;nofollow&#x22;"} wie `^8.1` oder `>=8.1,<8.3` übersetzt Knecht in einen [Semver-Range](https://github.com/npm/node-semver#ranges){rel="&#x22;nofollow&#x22;"} und nimmt die höchste Version, die ihn erfüllt. Erfüllt keine den Constraint, gilt der Default, mit Warnung im Run-Log.

### Das Ergebnis in den Settings

![Projekt-Settings eines Nuxt-Repos ohne DDEV-Config: die Karte "Environment" mit PHP 8.4, Node 24 und pnpm, darunter die Boot Commands und die Karte "Dev Server" mit Befehl und Port](https://knecht.works/assets/knecht-project-settings-noddev.png)

Die Karte "Environment" in den Projekt-Settings zeigt die erkannten Werte mit ihrer Quelle. Wer will, wählt dort eine andere PHP-Version, eine andere Node-Version oder einen anderen Package Manager. Die Erkennung läuft schon beim Verbinden des Repos, über die GitHub-API und mit derselben Logik wie beim Boot. Warnungen, etwa zu einem Constraint, den keine Version erfüllt, stehen ebenfalls in der Karte.

## Preview

Eine generierte Umgebung hat keine Website. Deshalb gibt es die Karte "Dev Server" mit dem Befehl, der den Dev-Server startet, etwa `npm run dev`, und seinem Port. Knecht startet ihn nach den Boot-Befehlen und liefert ihn als Preview der Session aus. Die Preview-URL bekommt der Befehl als `KNECHT_PREVIEW_URL`. Ohne Dev-Server bootet die Umgebung ohne Preview. Änderungen an den Karten "Environment" und "Dev Server" greifen beim nächsten Run der Session.

:update-video{caption="Ein Nuxt-Dev-Server als Preview. Die Änderung im Code erscheint ohne Reload." src="https://knecht.works/assets/hmr-nuxt-knecht.mp4"}

### Hot Reload

Hot Reload funktioniert in der Preview wie lokal, ohne Änderungen im Repo. Wie ein Vite-Dev-Server durchkommt, war aber ein Stück Arbeit.

::steps{level="4"}
#### Der Daemon im Container

Der Dev-Server läuft als Daemon unter [supervisord](https://supervisord.org/){rel=""nofollow""} im Web-Container, so wie DDEV es für [web\_extra\_daemons](https://docs.ddev.com/en/stable/users/configuration/config/#web_extra_daemons){rel=""nofollow""} vorsieht. Knecht trägt ihn in seiner Override-Datei ein, zusammen mit dem Forwarder aus dem nächsten Schritt:

```yaml
web_extra_daemons:
  - name: knecht-dev
    command: bash -lc 'npm run dev'
    directory: /var/www/html
  - name: knecht-forward
    command: knecht-forward 41000 3000
    directory: /var/www/html
```

Der Befehl läuft in einer Login-Shell, damit das Profil des Images gilt. DDEV startet den Daemon direkt nach `ddev start`, also bevor die Boot-Befehle `npm ci` ausgeführt haben. Der erste Start stirbt deshalb, und supervisord gibt nach ein paar Versuchen auf. Knecht startet die Daemon-Gruppe nach den Boot-Befehlen noch einmal und pollt dann, bis auf dem Port etwas antwortet. Erst dann gilt die Preview als bereit.

#### Der Forwarder

Vite, Nuxt und Next binden standardmäßig nur an `127.0.0.1`. Der Preview-Proxy erreicht den Container aber von außen, über dessen IP im Docker-Netz. Deshalb läuft als zweiter Daemon ein kleiner Forwarder daneben, ein Node-Script mit wenigen Zeilen. Es lauscht auf allen Interfaces des Containers an einem festen Port und reicht jede TCP-Verbindung an `127.0.0.1` und den Port des Dev-Servers weiter. Alles vom Host aus zielt auf den Forwarder, auch das Polling beim Boot, damit derselbe Weg geprüft wird, den später der Browser nimmt.

#### Der Proxy

Ein Request auf `<session>.preview.<host>` landet beim Preview-Proxy von Knecht. Der prüft das Login-Cookie, ermittelt die IP des Web-Containers und reicht den Request per HTTP an den Forwarder durch. Der `Host`-Header bleibt der Preview-Host, weil der Dev-Server keinen eigenen Hostnamen hat. Hot Reload läuft über eine [WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSockets_API){rel=""nofollow""}-Verbindung. Der Proxy leitet den Upgrade an denselben Port weiter und gibt das vom Browser gewünschte Subprotokoll mit, weil Vite den HMR-Upgrade nur mit `vite-hmr` abschließt. Weil der Forwarder rohes TCP weiterreicht, kommt der WebSocket ohne weiteres Zutun durch.

#### Die Host-Prüfung

Vite lehnt Anfragen für unbekannte Hostnamen ab, siehe [server.allowedHosts](https://vite.dev/config/server-options.html#server-allowedhosts){rel=""nofollow""}. Seit Vite 5.4.12 und 6.0.9 liest der Dev-Server einen zusätzlichen erlaubten Host aus der Umgebungsvariable `__VITE_ADDITIONAL_SERVER_ALLOWED_HOSTS`, und Knecht setzt sie auf den Preview-Host. Nuxt nutzt Vite und ist damit abgedeckt. Next.js führt seine eigene Liste in [`allowedDevOrigins`](https://nextjs.org/docs/app/api-reference/config/next-config-js/allowedDevOrigins){rel=""nofollow""}, die kommt weiterhin aus dem Repo.
::

### Dev-Server neben der eigenen Config

Seit demselben Release kann auch ein Repo mit eigener DDEV-Config einen Dev-Server angeben, etwa Vite für HMR neben einer [Craft](https://craftcms.com/){rel="&#x22;nofollow&#x22;"}-Site. Der Dev-Server ersetzt die Site dann nicht. Die Hostnamen des Repos erreichen weiter den Web-Server, und der Dev-Server bekommt eine eigene Preview-Origin, die der Container als `KNECHT_DEV_SERVER_URL` sieht. Dorthin zeigt das Repo seine Asset-URL, etwa mit einem Env-Wert wie `VITE_DEV_SERVER_PUBLIC=$KNECHT_DEV_SERVER_URL` in den Projekt-Settings.

Die Seite lädt den Dev-Server als Module-Script, und Module-Scripts holt der Browser über Origins hinweg ohne Cookies. Das Login-Cookie der Preview kommt dort also nie an. Deshalb trägt die Origin des Dev-Servers einen Token pro Session im Hostnamen, statt am Cookie zu hängen. Sichtbar ist davon nichts, `KNECHT_DEV_SERVER_URL` enthält die fertige URL.

## Nebenbei gelernt

Ein Teil der Arbeit an diesem Release war weniger die Erkennung als das Zusammenspiel mit DDEV, Docker Compose und Nuxt. Fünf Dinge davon sind auch außerhalb von Knecht nützlich.

### DDEV merged nach Dateinamen

DDEV liest alle `config.*.yaml` in `.ddev/` und merged sie in alphabetischer Reihenfolge, bei Skalaren gewinnt die letzte Datei, Listen werden zusammengehängt ([Doku](https://docs.ddev.com/en/stable/users/extend/customization-extendibility/){rel="&#x22;nofollow&#x22;"}). Knechts Override hieß `config.knecht.yaml`. Ein Repo mit einer `config.vite.yaml` sortierte dahinter und konnte den Run-Namen oder die Umgebung überschreiben. Jetzt heißen Knechts Dateien `config.zzz-knecht.yaml` und `docker-compose.zzz-knecht.yaml`, damit sie zuletzt gelesen werden.

Beim Merge ignoriert DDEV außerdem Nullwerte. Ein `xdebug_enabled: false` in einer Override-Datei hebt ein `true` aus der Haupt-Config nicht auf. Auf einem Knecht-Server läuft kein Debugger, jeder Request hätte auf einen gewartet. Knecht schaltet Xdebug deshalb über [`XDEBUG_MODE=off`](https://xdebug.org/docs/all_settings){rel="&#x22;nofollow&#x22;"} in der Umgebung ab, die Variable schlägt die ini, für php-fpm und die CLI. Eine eigene `XDEBUG_MODE`-Zeile in den Projekt-Settings gewinnt trotzdem.

### Variablen ohne Router

Ohne Router lässt DDEV [`DDEV_PRIMARY_URL`](https://docs.ddev.com/en/stable/users/extend/custom-commands/#environment-variables-provided){rel="&#x22;nofollow&#x22;"}, `DDEV_HOSTNAME` und `DDEV_SCHEME` leer. Auf Knecht-Servern gibt es keinen Router, der Preview-Proxy spricht die Web-Container direkt an. Die Settings-Dateien, die DDEV selbst für Drupal, TYPO3 und WordPress schreibt, bauen ihre URLs aber aus genau diesen Variablen, und so zeigten sie ins Leere. Knecht schreibt sie jetzt selbst, so wie DDEV es lokal tut, mit der Preview-URL der Session als Wert.

### Ports aus der Projektliste

Zwei parallele Runs desselben Projekts brauchen verschiedene Host-Ports, auch wenn das Repo für den GUI-Client eines Entwicklers einen [`host_db_port`](https://docs.ddev.com/en/stable/users/configuration/config/#host_db_port){rel="&#x22;nofollow&#x22;"} pinnt. Knecht hat freie Ports beim Betriebssystem erfragt, und DDEV lehnte den Start trotzdem ab:

```text
host port 36865 has already been allocated to project knecht-run-6
```

DDEV merkt sich die Ports jedes Projekts in `~/.ddev/project_list.yaml`, auch die von gestoppten, und prüft gegen diese Liste. Knecht liest die Liste jetzt mit und probiert weiter, bis es Ports hat, die DDEV nicht kennt.

### Docker Compose expandiert gegen den Host

Die Env-Werte aus den Projekt-Settings landen über eine Compose-Datei im Container. Docker Compose [interpoliert](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/){rel="&#x22;nofollow&#x22;"} ein `$NAME` in dieser Datei gegen die Umgebung des Hosts, nicht des Containers. Ein nicht gesetzter Name wurde ein leerer String, ein Passwort mit `$` kam verstümmelt an. Knecht expandiert Referenzen jetzt selbst, gegen `KNECHT_PREVIEW_URL` und die vorherigen Zeilen, und escaped jedes übrige `$` als `$$`. `APP_URL=$KNECHT_PREVIEW_URL` ergibt so die Preview-URL der Session, `SITE_URL=${APP_URL}/en` baut darauf auf, und ein `$` im Passwort bleibt ein `$`.

### Nuxt hinter Nuxt

Das Dashboard ist eine Nuxt-App, und die Preview eines Nuxt-Projekts läuft über einen Proxy in derselben App. Beide liefern ihre Assets unter `/_nuxt/` aus. [Vites](https://vite.dev/){rel="&#x22;nofollow&#x22;"} Dev-Middleware und [Nitros](https://nitro.build/){rel="&#x22;nofollow&#x22;"} Static-Handler beantworten Anfragen auf diesen Pfad, bevor eine Server-Middleware dran ist. Die Assets der Preview kamen also beim Dashboard an und liefen ins Leere, 404 in Production und ENOENT im Dev-Modus. Die Lösung ist eine Zeile in der `nuxt.config.ts`, [buildAssetsDir](https://nuxt.com/docs/api/nuxt-config#buildassetsdir){rel="&#x22;nofollow&#x22;"} auf `/_knecht/`. Wer eine Nuxt-App durch eine Nuxt-App proxyt, braucht sie auch.

## Einschränkungen

Die generierte Umgebung ist ein DDEV-Projekt mit PHP und Node, mehr nicht. Damit läuft alles, was mit diesen beiden auskommt, also Libraries, Plugins, Frontends und Node-Tools. Was darüber hinausgeht, braucht weiterhin eine eigene `.ddev/config.yaml` im Repo:

- eine Datenbank, weil die generierte Umgebung keinen Datenbank-Container hat
- zusätzliche Dienste wie Redis oder Elasticsearch
- andere Laufzeiten wie Python, Ruby oder Go, die das DDEV-Image nicht mitbringt

Repos, die statt DDEV eine eigene docker-compose-Datei mitbringen, kann Knecht weiterhin nicht booten.

::callout{color="neutral" icon="i-lucide-arrow-right"}
Fälle, in denen ein Projekt auf Knecht anders läuft als lokal, sammeln wir mit dem Fix je Framework in den Docs unter [Troubleshooting](https://knecht.works/docs/resources/troubleshooting).
::


# Zurück zum geteilten Daemon, eine Preview für 180 MB

::note
Dieser Post ist die Fortsetzung von [Vom geteilten Docker Daemon zur Sandbox pro Run](https://knecht.works/updates/dashboard-architecture). Dort steht, warum wir uns für eine eigene Sandbox pro Run entschieden haben. Hier steht, warum wir sie wieder ausgebaut haben.
::

Der letzte Architektur-Post endete mit einem klaren Plan. Jeder Run bekommt seine eigene [Sysbox](https://github.com/nestybox/sysbox){rel="&#x22;nofollow&#x22;"}-Sandbox mit eigenem [Docker Daemon](https://docs.docker.com/get-started/docker-overview/#docker-architecture){rel="&#x22;nofollow&#x22;"}. Wir haben das gebaut, und es lief. Trotzdem haben wir die Sandbox wieder ausgebaut, denn zwei Probleme, die wir bewusst aufgeschoben hatten, ließen sich nicht mehr aufschieben.

## Die Rechnung

Eine Sysbox-Sandbox ist im Grunde ein kleines Betriebssystem mit [systemd](https://systemd.io){rel="&#x22;nofollow&#x22;"}, eigenem Docker Daemon und darüber dem kompletten [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"}-Stack. Dass das Ressourcen kostet, war uns von Anfang an klar. Wir dachten nur, wir bekommen das später in den Griff, dem war aber leider nicht so.

- Eine laufende Preview kostete gemessen rund 3 GB RAM. Bei 20 parallelen Previews wären das 60 GB, nur für Sandboxes.
- Jede Sandbox braucht alle DDEV-Images einmal für sich, das sind 1-2 GB Disk pro Preview. Ein Registry-Cache beschleunigte die Downloads, am Platz änderte er nichts.

Das Ziel von Knecht ist aber, dass eine Agentur alle ihre Projekte auf einem eigenen, bezahlbaren Server laufen lässt. Dafür ist eine Architektur mit 3 GB pro Preview das falsche Fundament, egal wie sauber sie isoliert.

## Was die Sandbox löste

Zur Erinnerung, der letzte Post hatte zwei Gründe für die Sandbox.

- Auf dem geteilten Daemon gab es keine Isolation zwischen Runs. Die festen Ports des [DDEV-Routers](https://docs.ddev.com/en/stable/users/usage/architecture/){rel="&#x22;nofollow&#x22;"} kollidierten, deshalb mussten wir ihn weglassen und in die DDEV-Config eingreifen.
- Der Agent führt fremden Code aus, und wer den [Docker-Socket](https://docs.docker.com/engine/security/#docker-daemon-attack-surface){rel="&#x22;nofollow&#x22;"} des Hosts erreicht, kontrolliert den ganzen Server.

Die Sandbox löste beides mit einem Schlag. Aber sie war die gründlichste Lösung, nicht die einzige. Der Rückbau war erst möglich, als wir beide Probleme noch einmal einzeln angeschaut haben.

## Die neuen Lösungen

### Kein Socket im Run

Das Problem ist der Docker-Socket. Der Agent führt fremden Code aus, und sobald der Socket in seiner Umgebung liegt, kontrolliert ein gekaperter Agent den ganzen Server. Die Sandbox hat deshalb jedem Run einen eigenen Daemon gegeben, damit der Socket des Hosts außer Reichweite bleibt.

Unsere Lösung setzt früher an, der Run bekommt überhaupt keinen Docker-Zugriff mehr. Knecht fährt DDEV host-seitig hoch. Der Agent und alle Projekt-Befehle wie `composer install` laufen ausschließlich im Web-Container des Projekts. Ein Agent, der per [Prompt Injection](https://simonwillison.net/series/prompt-injection/){rel="&#x22;nofollow&#x22;"} gekapert wird, steht damit in einem ganz normalen Container mit eigenem Netz und begrenzten Ressourcen, und er findet dort weder Socket noch Daemon vor.

### Umbenennen statt einsperren

Die Port-Kollisionen kamen allein vom Router, dem Reverse Proxy, den DDEV vor alle Projekte stellt und der die Ports 80 und 443 auf dem Host bindet. Der bleibt weiter weg. Stattdessen spricht der Preview-Proxy den Web-Container jedes Runs direkt über das [Docker-Netzwerk](https://docs.docker.com/engine/network/){rel="&#x22;nofollow&#x22;"} an.

Eine Sache muss der Proxy dabei mitliefern, den Hostnamen. Projekte mit mehreren Domains, etwa ein [Craft-Multisite](https://craftcms.com/docs/5.x/system/sites.html){rel="&#x22;nofollow&#x22;"}, entscheiden anhand der aufgerufenen Domain, welche Site sie ausliefern. Die Preview läuft aber unter einer Knecht-URL, nicht unter der echten Domain des Projekts. Deshalb schickt der Proxy die echte Domain im [Host-Header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Host){rel="&#x22;nofollow&#x22;"} mit, und für das Projekt sieht jede Anfrage so aus, als wäre sie über die normale URL gekommen.

Damit parallele Runs desselben Projekts sich nicht in die Quere kommen, registriert Knecht jeden Run als eigenes DDEV-Projekt mit eindeutigem Namen. Der Eingriff in die DDEV-Config, im letzten Post noch ein Minuspunkt, ist geblieben, aber er ist für das Projekt unsichtbar. Der Code im Repo bleibt unangetastet, umgeschrieben wird nur die generierte Laufzeit-Config.

## Der Tradeoff

Sicherheitstechnisch ist das ein Rückschritt gegenüber Sysbox. Sysbox mappte Root im Container über [User Namespaces](https://man7.org/linux/man-pages/man7/user_namespaces.7.html){rel="&#x22;nofollow&#x22;"} auf einen unprivilegierten Host-User. Jetzt laufen die Container wieder mit [runc](https://github.com/opencontainers/runc){rel="&#x22;nofollow&#x22;"}, der normalen Docker-Runtime, die Grenze zum Host ist dünner. Aufgefangen wird das durch genau die Punkte von oben, denn der Run hat keinen Socket, ein eigenes Netz und feste Limits.

Ob dieser Rückschritt vertretbar ist, entscheidet wie schon im letzten Post das [Threat Model](https://owasp.org/www-community/Threat_Modeling){rel="&#x22;nofollow&#x22;"}. Knecht läuft bei einer Agentur, für ihre eigenen Projekte, auf ihrem eigenen Server. Der Angreifer, vor dem die Sandbox zusätzlich geschützt hätte, braucht einen Kernel-Exploit und landet dann auf einem Server, auf dem ohnehin nur die eigenen Projekte liegen. Für dieses Risiko 3 GB statt 180 MB pro Preview zu bezahlen, ist der falsche Tausch.

## Das Ergebnis

Beide Varianten liefen auf derselben Dev-Maschine, gemessen im Juli 2026:

|                           | Sandbox pro Run (Sysbox)            | DDEV auf dem Host (heute)         |
| ------------------------- | ----------------------------------- | --------------------------------- |
| RAM pro laufender Preview | \~3 GB                              | \~180 MB                          |
| DDEV-Images               | pro Sandbox, 1-2 GB extra           | einmal pro Host                   |
| Gestoppte Preview wecken  | Minuten, kompletter Sandbox-Boot    | Sekunden                          |
| Docker-Zugriff im Run     | eigener Daemon in der Sandbox       | keiner, Knecht steuert von außen  |
| Isolationsgrenze          | eigener Daemon plus User Namespaces | eigenes Netz, Limits, kein Socket |

Dazu kommen noch zwei kleinere Optimierungen.

- Die Datenbank läuft für die Preview mit einer sparsameren Konfiguration. Die MySQL-Config, die DDEV mitliefert, erlaubt jeder Datenbank rund 1 GB [Puffer](https://mariadb.com/kb/en/innodb-buffer-pool/){rel="&#x22;nofollow&#x22;"}.
- Eine gestoppte Preview kostet 0 RAM, übrig bleiben nur Datenbank-Volume und Code.

Aus "ein paar Previews pro Server" wurde damit "praktisch alle Projekte einer Agentur gleichzeitig".

## Was wir mitnehmen

Der letzte Post begann mit dem Satz, dass wir die riskanteste Annahme zuerst testen. Das war richtig, und es hat funktioniert, die Sandbox lief. Nur war "läuft es?" die falsche letzte Frage. Die vollständige lautet "läuft es zu Kosten, die zum Ziel passen?", und die lässt sich erst beantworten, wenn das System unter echter, paralleler Last steht. Diese Messung machen wir jetzt früher.


# Knecht antwortet jetzt auf GitHub

Bisher lief bei Knecht alles in eine Richtung. Ein [Trigger](https://knecht.works/updates/workflow-engine) feuerte, ein Workflow lief, und das Ergebnis lag im Dashboard. Wer im GitHub-Issue auf eine Antwort wartete, sah dort nichts. Mit diesem Update arbeitet Knecht dort, wo die Arbeit gemeldet wird. Er antwortet und labelt direkt im Issue-Thread, und mit einer Mention im Kommentar schickt ihr ihn zurück an die Arbeit.

## Vom Bug-Report zum PR

So sieht das auf unserem Craft-Testprojekt aus. Jemand meldet per Issue, dass die Seite keinen Dark Mode hat. Ein Trigger startet den Workflow "Classify Issue". Knecht bootet die Seite in ihrer [Preview-Umgebung](https://knecht.works/updates/sandbox-rollback), stellt den Report nach und findet heraus, dass Dark Mode schlicht nie implementiert wurde. Er setzt das vorhandene Label `enhancement` und antwortet dem Reporter im Thread.

![GitHub-Issue mit einem Dark-Mode-Bug-Report, unter dem die App knecht-works das Label enhancement gesetzt hat](https://knecht.works/assets/issue-creation-with-label.png)

Die Antwort enthält den Befund und einen konkreten Plan für die Umsetzung, mit der Preview-URL am Ende.

![Kommentar der App knecht-works im Issue mit Befund und Umsetzungsplan, darunter ein Kommentar des Teammitglieds mit einer Mention und einer Augen-Reaktion](https://knecht.works/assets/issue-follow-up.png)

Ein Teammitglied liest die Analyse und antwortet mit einer Mention, sinngemäß "@knecht-works, setz das um und öffne einen PR". Knecht bestätigt sofort mit einer Augen-Reaktion und arbeitet weiter, in derselben Umgebung und demselben Gespräch wie die Triage. Er kennt also den Befund und den Plan schon. Ein paar Minuten später steht die Antwort im Thread, mit dem geöffneten PR und der Preview-URL.

![Antwort der App knecht-works im Issue mit einer Zusammenfassung der beiden Commits, am Ende Preview-URL und PR-Link](https://knecht.works/assets/issue-enhancement-finished.png)

Dass der Fix auf der Triage aufbauen kann, liegt an der größten Änderung dieses Updates, den Sessions.

## Eine Session pro Issue

Bisher war jede Workflow-Ausführung ihre eigene Welt, mit eigenem Checkout, eigener Umgebung und eigenem Agenten-Gespräch. Beim Bauen der Antwort-Schleife hat sich gezeigt, dass das die falsche Einheit ist, denn Umgebung und Kontext gehören zum Issue, nicht zur einzelnen Ausführung. Deshalb gibt es jetzt Sessions. Eine Session gehört zu genau einem Issue oder PR und hält dessen Checkout, dessen Umgebung und ein gemeinsames Agenten-Gespräch. Darin laufen die Runs, also einzelne Workflow-Ausführungen, und Follow-ups, also einzelne Nachrichten an den Agenten.

![Projektseite im Knecht-Dashboard mit der Run-Liste, gruppiert nach Issues, unter dem Dark-Mode-Issue vier Runs von der Triage bis zu zwei Mentions](https://knecht.works/assets/knecht-project-triggers-in-action.png)

Die Projektseite und die Run-Übersicht gruppieren Runs jetzt nach Session. Im Screenshot gehören vier Runs zum Dark-Mode-Issue, von "Classify Issue" bis zu den beiden Mentions, alle in derselben Umgebung. Im Detail heißt das:

- Feuern zwei Trigger auf dasselbe Issue, laufen sie nacheinander in der Session, nie parallel.
- Wird das Issue geschlossen, schließt auch die Session. Ein Reopen belebt sie wieder, solange ihre Umgebung noch existiert.
- Beim Archivieren einer Umgebung sichert Knecht jetzt auch das Gespräch des Agenten, ein paar Megabyte. Es übersteht damit einen Archive-Restore-Zyklus.
- Events ohne Issue oder PR, also Push, Zeitplan und manueller Start, verhalten sich wie bisher und bekommen eine Session mit einem einzigen Run.

Wird eine Umgebung ganz abgebaut, ist das Gespräch weg. Der Agent setzt dann nicht stumm bei null an, sondern liest den GitHub-Thread, die Ergebnisse der bisherigen Actions und das [Projekt-Gedächtnis](https://knecht.works/updates/agent-memory), und sagt im Thread dazu, dass er neu ansetzt. Bestehende Installationen müssen dafür nichts tun, das Update stellt vorhandene Runs und Umgebungen beim Start automatisch auf Sessions um.

## Das Beispiel Cloudflare

Dass sich Issue-Triage komplett automatisieren lässt, hat Cloudflare im August 2026 am Repository des Astro-Frameworks gezeigt. Ihr [Triage-System](https://blog.cloudflare.com/astro-issue-triage/){rel="&#x22;nofollow&#x22;"} reproduziert jeden Report, diagnostiziert die Ursache und baut den Fix, die offenen Issues sind damit von über 200 auf rund 30 gefallen. Es ist allerdings ein eigenes Stück Software, von einem Team bei Cloudflare für genau dieses Repository gebaut. Bei Knecht ist derselbe Ablauf ein Workflow, den ihr auf eure eigenen Projekte legt, und die Session bringt die gebootete Seite gleich mit.

## Wie es weitergeht

Als Nächstes gehen wir Jira an. Die Konzepte bleiben dieselben, ein Ticket bekommt seine Session mit Umgebung und Gespräch, und Antworten und Mentions funktionieren im Ticket genauso wie im Issue-Thread.


# Was macht der Knecht

Ein Bugreport beginnt immer mit dem Versuch, den Fehler zu reproduzieren. Und nach dem Fix muss man sicherstellen, dass er wirklich behoben ist. Oder?

## Motivation

Agenturen betreuen oft viele Projekte. Diese sind häufig unterschiedlich konfiguriert oder laufen nur auf dem Rechner des einen Mitarbeiters, der von Anfang an dabei ist. Trotzdem brauchen alle regelmäßig Security-Updates und Bugfixes.

Damit AI Agents hier wirklich helfen können, brauchen wir vollständig lauffähige Projekte.

### Security Updates

Um ein Security-Update in ein CMS einzuspielen, ist fast immer eine laufende Datenbank nötig – denn nach einem Update können Datenbank-Migrationen anstehen. Dependabot und andere Bots können deshalb nicht einfach ein `composer update` machen und live ausrollen.

### Bug fixes

Leider ist es nicht immer so einfach:

::prompt{description="Pls fix!"}
<https://youtu.be/dQw4w9WgXcQ?t=0>{rel=""nofollow""}
::

Für einen Bugfix muss zuerst ein Mitarbeiter frei sein – im besten Fall einer, der das Projekt schon lokal laufen hat, um den Fehler nachhaltig zu lösen. Und wenn nicht?

## DDEV

DDEV ist eine Docker-basierte Entwicklungsumgebung. Mit ihr lässt sich ein Projekt vollständig betreiben, ohne Entwickler-Tools direkt auf dem Gerät zu installieren.

So fährt jedes Projekt reproduzierbar und isoliert hoch: Web und Datenbank kommen sauber konfiguriert und immer auf die gleiche Weise. Genau diese Verlässlichkeit ist die Grundlage für alles Weitere. Denn was sich auf Knopfdruck immer gleich booten lässt, kann auch eine Maschine booten.

## Was der Knecht macht

Knecht wird als Dashboard gebaut, das du auf deinem eigenen Server hostest – so behältst du die Daten. Im Dashboard gibt es Preview-Links und Screenshots (über Penthouse), mit denen du einen Bugfix direkt verifizieren kannst.

### How it works

In Knecht gibt es Projekte, Workflows und Trigger.

::steps{level="3"}
### Projekte

Ein Projekt besteht immer aus einem GitHub-Repository, in dem DDEV bereits konfiguriert ist. Darin lassen sich dann noch Environment-Variablen und die Datenbank festlegen.

### Workflows

Ein Workflow ist ein vordefinierter Prozess, der mit Projekten arbeitet. Er kann zum Beispiel so aussehen: Projekt booten → Composer-Pakete updaten → PR mit den Änderungen erstellen. Die Schritte werden also deterministisch abgearbeitet.

Bugfixes sind aber selten immer gleiche, wiederholbare Schritte. Hier kommen AI Agents ins Spiel: Über Opencode können sie einen Bug im laufenden Projekt reproduzieren und beheben.

### Trigger

Ein Trigger ist der Startpunkt eines Workflows. Über Webhooks – etwa von Jira oder GitHub – kann der Knecht vordefinierte Workflows automatisch starten und die Ergebnisse später als Pull Request liefern.
::


# Ein Terminal und VS Code für jeden Run

Ein Run ist eine einzelne Ausführung eines [Workflows](https://knecht.works/updates/workflow-engine) auf einem Projekt, mit eigener Umgebung auf dem Server. Bisher kam man an diese Umgebung nur über das Dashboard heran. Man konnte dem Agenten Anweisungen schicken und die Preview anschauen, aber nicht selbst hinein. Wer nur kurz ein Log lesen oder einen Befehl ausprobieren wollte, musste dafür den Agenten bemühen. Jetzt gibt es auf der Run-Seite drei direkte Wege hinein.

## Das Terminal

Der direkteste Weg in einen Run ist eine Shell. Es gibt sie in zwei Varianten, im Browser für jedes Dashboard-Mitglied und über SSH für alle, die ohnehin auf den Server dürfen. Das Video zeigt beide.

:update-video{caption="Das Terminal im Browser und der fertige SSH-Befehl" src="https://knecht.works/assets/knecht-ssh-showcase.webm"}

### Im Browser

Ein Klick auf "Terminal" öffnet eine Shell im Container des Runs. Sie geht als Fenster direkt auf der Run-Seite auf, man tippt also im selben Browser-Tab, in dem man den Run gerade anschaut. Ein Terminal-Programm oder ein SSH-Client auf dem eigenen Rechner ist dafür nicht nötig.

- Funktioniert für jedes Dashboard-Mitglied, ganz ohne Zugang zum Server.
- Die Shell läuft im selben Container wie der Agent. Composer, npm und Git sind da und verhalten sich wie im echten Projekt.
- Es geht kein zusätzlicher Port auf, die Verbindung läuft über dieselbe HTTPS-Verbindung wie das Dashboard.
- Läuft ein Run mit mehreren Containern, etwa einer eigenen Datenbank, hat das Terminal einen Tab pro Service.

::note
Knecht stoppt die Umgebung eines Runs automatisch, wenn sie eine Weile niemand benutzt, damit sie keinen RAM belegt. Arbeit im Terminal zählt dabei als Benutzung, die Umgebung bleibt also an, solange man darin tippt.
::

### Über SSH

Wer lieber im eigenen Terminal arbeitet, findet im Terminal-Fenster einen fertigen SSH-Befehl zum Kopieren. Auf der eigenen Maschine eingefügt, landet er in genau demselben Container.

```bash
ssh -t knecht@my-server.com docker exec -it -u 1000:1000 -w /var/www/html -e HOME=/home/node -e USER=node ddev-knecht-run-4-web bash -l
```

Knecht betreibt dafür keinen eigenen SSH-Server und verwaltet keine Keys. Der Befehl nutzt den SSH-Zugang zum Server, den es sowieso schon gibt. In den Einstellungen wird dafür einmal die SSH-Adresse des Servers hinterlegt, mehr nicht. Dieser Weg ist damit denen vorbehalten, die ohnehin auf den Server dürfen. Für alle anderen bleibt das Web-Terminal.

## VS Code im Browser

VS Code läuft direkt im Run. Ein Klick auf "Open in VS Code" auf der Run-Seite öffnet die IDE als neuen Browser-Tab. Dahinter steckt [openvscode-server](https://github.com/gitpod-io/openvscode-server){rel="&#x22;nofollow&#x22;"}, der Open-Source-Build von VS Code für den Browser.

:update-video{caption="VS Code öffnet den Run im Browser" src="https://knecht.works/assets/knecht-vs-code.webm"}

Die IDE arbeitet dabei direkt am Projekt im Run, nicht an einer Kopie. Eine gespeicherte Änderung liegt sofort im laufenden Projekt, es ist derselbe Code, den auch die Preview und der Agent sehen. Und weil jeder Run ein vollwertiger Git-Clone ist, funktionieren Commits und Branches in IDE und Terminal ganz normal.

Ein lokales Setup braucht es nicht. Die IDE läuft für jedes Dashboard-Mitglied im Browser und ist wie die Previews nur mit Knecht-Login erreichbar.


# DDEV-Projekte automatisieren mit Workflows

Ein Workflow ist eine Liste von Schritten, die Knecht automatisch für ein Projekt ausführt. Zum Beispiel Projekt starten, Composer-Pakete updaten, Tests laufen lassen und einen Pull Request öffnen. Die letzten Wochen sind fast komplett in diese Engine geflossen. Hier steht, was sie kann, was die AI-Action von einem Chat unterscheidet und was noch fehlt.

![Der Workflow-Editor mit Trigger, Schritten und der Action-Bibliothek](https://knecht.works/assets/workflow-detail.png)

## Wie ein Workflow läuft

Wird ein Workflow gestartet, entsteht ein **Run**, eine einzelne Ausführung auf einem Projekt. Jeder Run bekommt eine eigene, abgeschottete Umgebung, die **Sandbox**. Darin läuft das Projekt komplett, der Code frisch von GitHub, die Datenbank eingespielt, [DDEV](https://ddev.com){rel="&#x22;nofollow&#x22;"} gestartet. Das Live-System und andere Runs bekommen davon nichts mit. Warum jeder Run seine eigene Sandbox bekommt, steht im [Architektur-Post](https://knecht.works/updates/dashboard-architecture).

Die Schritte laufen nacheinander, und jeder hinterlässt Ergebnisse, die spätere Schritte über Platzhalter einsetzen.

```text
{{ steps.run_tests.stdout }}      die Ausgabe des Schritts "Run tests"
{{ inputs.title }}                der Titel des Tickets, das den Workflow gestartet hat
```

Auswendig wissen muss man das nicht. Wer `{{ `tippt, bekommt eine Liste mit allem, was an dieser Stelle verfügbar ist. Und nach jedem Schritt speichert Knecht, was passiert ist. Deshalb sieht man live, wo ein Run steht, und ein fehlgeschlagener Run lässt sich genau ab dem Schritt fortsetzen, an dem er hängen blieb.

## Die Actions

Jeder Schritt führt eine Action aus. Grob gibt es drei Sorten.

::field-group
  :::field{name="Deterministische Actions"}
  Erledigen genau eine Sache, immer gleich. Sie booten das Projekt, führen einen Shell-Befehl wie `composer update` aus, lassen eigenen JavaScript-Code laufen, rufen eine externe URL auf, prüfen die ganze Sitemap auf kaputte Links oder bringen die Änderungen als Pull Request zurück nach GitHub.
  :::

  :::field{name="Kontrollfluss-Actions"}
  If/else führt Schritte nur unter einer Bedingung aus, zum Beispiel "wenn die Tests fehlgeschlagen sind". Loop wiederholt Schritte für jeden Eintrag einer Liste.
  :::

  :::field{name="AI-Action"}
  Lässt einen Agenten im laufenden Projekt arbeiten, dazu gleich mehr.
  :::
::

Weil nicht jeder Fehler ein echter Fehler ist, hat jeder Schritt seine eigene Fehler-Policy. Wackelige Befehle bekommen Retries mit Backoff, und mit `continueOnError` läuft der Run trotz Fehler weiter. Die Bibliothek wächst gerade noch, einen teil der aktuellen Actions können im oberen Screenshot angesehen werden.

### Ein Agent, kein Chat

Die AI-Action startet [opencode](https://opencode.ai){rel="&#x22;nofollow&#x22;"} mit eurem eigenen API-Key direkt in der Sandbox. Der Agent arbeitet im echten, laufenden Projekt, er liest Code, ändert Dateien und führt Befehle aus. Ein Chat sagt dir, wie ein Fix aussehen könnte. Der Agent wendet ihn an und probiert aus, ob er funktioniert.

![Die AI-Action mit Prompt, festem Output-Format und den verfügbaren Variablen](https://knecht.works/assets/workflow-ai-action.png)

Statt Fließtext kann der Agent feste Output-Felder wie `prTitle` liefern, als geprüftes JSON für spätere Schritte. Und er ist nach dem Run nicht weg. Ein Chat auf der Run-Seite setzt dieselbe Session fort, "Mach den Button noch blau" braucht keinen neuen Run.

### Sicher eingesperrt

Alles, was ein Workflow ausführt (Shell-Befehle, eigener Code, der Agent), läuft ausschließlich in der Sandbox, nie auf dem Server selbst.

Auch Projekt-Secrets bleiben, wo sie hingehören. API-Keys und Tokens liegen [verschlüsselt](https://knecht.works/updates/gh-auth-evolution) in der Datenbank. Die Preview-URLs sind ebenfalls nicht öffentlich, denn wer eine öffnet, braucht einen Knecht-Login.

## Die Trigger

Ein Trigger legt fest, wann ein Workflow von selbst startet. Das ist der Punkt, an dem aus einem Werkzeug Automatisierung wird, denn niemand muss mehr daran denken, den Ablauf anzustoßen. Der Workflow läuft, sobald seine Bedingung eintritt, auch nachts und am Wochenende. Aktuell gibt es drei Arten.

::field-group
  :::field{name="Manuell"}
  Per Klick im Dashboard oder als Test-Run direkt im Editor.
  :::

  :::field{name="Integrationen"}
  Knecht reagiert auf Events aus GitHub und Jira. Bekommt ein Jira-Ticket zum Beispiel das Label "knecht", startet der Workflow, und der fertige PR-Link landet als Kommentar auf dem Ticket.
  :::

  :::field{name="Cron"}
  Nach Zeitplan, zum Beispiel jeden Montag um 6 Uhr die Security-Updates prüfen.
  :::
::

Ein Trigger kann mehrere Projekte anhängen und startet für jedes einen eigenen Run.

## Nach dem Start

Bevor ein Trigger scharf geschaltet wird, lässt sich der Workflow direkt im Editor testen, gegen ein echtes Projekt in einer eigenen Sandbox. Für Test-Runs gilt dabei dasselbe wie für echte.

![Ein Test-Run direkt im Editor, mit Live-Log und laufendem Schritt](https://knecht.works/assets/workflow-test-run.png)

Innerhalb eines Runs läuft alles bewusst nacheinander, parallele Zweige gibt es nicht. Ein Run bleibt eine lineare, nachvollziehbare Kette. Wie viele Runs gleichzeitig laufen, ist konfigurierbar, alles darüber wartet in der Queue.

## Workflows als Code

Jeder Workflow lässt sich als YAML oder JSON exportieren und wieder importieren. Damit wandert ein Workflow ins Git-Repo, bekommt Reviews wie jeder andere Code und lässt sich zwischen Projekten oder Instanzen kopieren. Wer lieber im Texteditor arbeitet, schreibt die Datei direkt und importiert sie fertig.

Das Format öffnet auch die Tür für später. Ein Workflow, der sich bei einer Agentur bewährt hat, funktioniert bei der nächsten genauso, weil er nur aus Schritten und Platzhaltern besteht. Denkbar ist ein Workflow-Store, aus dem man sich fertige Abläufe wie Security-Updates oder Link-Checks direkt installiert, statt sie selbst zusammenzuklicken.

## Was noch fehlt

Ein Benachrichtigungssystem gibt es noch nicht. Schlägt ein Run fehl, sieht man das bisher nur im Dashboard. Wer es sofort wissen will, ruft mit dem HTTP-Schritt am Ende des Workflows einen Slack-Webhook auf. Auch ein hartes Zeitlimit pro Run fehlt noch, ein hängender Schritt läuft, bis man ihn abbricht.