Prerequisites
You need just three things on your machine:
- Docker (24+) and Docker Compose v2 — verify with
docker --versionanddocker compose version. - Free port 8080 for the web app and port 5432 for Postgres (bound to localhost only, so reachable only from your machine).
- Around 5 GB free disk space for container images, the JAR build cache and the first workspaces.
claude, you'll need that CLI locally and start the factory natively instead of in the container — the app image contains no agent CLI (see the tutorial). For the mock adapter, nothing extra is needed.
1. Get the distribution bundle
The factory is a licensed product — there is no public repo. After purchase or trial unlocking you receive the distribution bundle. Open a terminal, unpack it and enter the folder:
tar xzf softwarefabrik-einzelplatz.tar.gz cd softwarefabrik
The bundle contains the docker-compose.yml (containers for the app and Postgres), the signed JAR and a sample .env. Just want to look without installing? Use the live demo.
2. Create the .env file
The platform reads a .env file with mandatory variables on startup. The file lives in the unpacked bundle directory (./softwarefabrik/.env) — it holds secrets, so keep it out of version control and backups. Replace the example values with strong secrets of your own:
# Bootstrap admin (login account on first start) SOFTWAREFABRIK_ADMIN_USER=admin SOFTWAREFABRIK_ADMIN_PASSWORD=ChangeMe-2026! # Database access (for Postgres in the container; password at least 16 characters) SOFTWAREFABRIK_DB_USER=softwarefabrik SOFTWAREFABRIK_DB_PASSWORD=DbSecret-2026! # Master key for encrypting API keys (32 bytes, base64) SOFTWAREFABRIK_SECRETS_MASTER_KEY=<paste your key here> # Attestation signing: the container profile requires a key, otherwise the app # does not start. Switch it off for a trial (the hash chain keeps running). SOFTWAREFABRIK_ATTESTATION_SIGNING_ENABLED=false
Generate the master key with a one-liner. On Linux/macOS:
openssl rand -base64 32
On Windows (PowerShell):
[Convert]::ToBase64String((1..32 | ForEach-Object { Get-Random -Maximum 256 }))
SOFTWAREFABRIK_ADMIN_PASSWORD, the platform deliberately does not create a bootstrap admin — you won't be able to log in. Weak defaults like admin/admin would be a security bug, so we require an explicitly set password. The master key must be at least 32 bytes long; without it the platform refuses to start. The same goes for SOFTWAREFABRIK_DB_USER: without it docker compose aborts. For production keep attestation signing on and provide an Ed25519 key (SOFTWAREFABRIK_ATTESTATION_PRIVATE_KEY, see the administration manual). Changing it later means previously stored API keys can no longer be decrypted — pick once, back it up, then leave it alone.
3. Start the platform
Start the containers in the background:
docker compose up -d docker compose logs -f app
The first run pulls the images and builds the app — this takes about 2–4 minutes. Flyway applies the database migrations (V1..V69). As soon as the logs report Started SoftwarefabrikApplication, the platform is ready.
You can also poll the health endpoint:
curl -f http://localhost:8080/actuator/health
# expects: {"status":"UP"}
Now open your browser at http://localhost:8080.
4. Log in
You land on the login page. Use the credentials from your .env:
- Username:
admin(or whatever you set inSOFTWAREFABRIK_ADMIN_USER) - Password:
ChangeMe-2026!(or your own value)
After a successful login you reach the dashboard with KPI tiles (everything is at zero, which is correct on a fresh instance), a list of your most recent projects and your most recent runs.
docker compose logs app | grep -i admin — usually the env variable is missing.
5. First project with the wizard
Open Projects and click "New project with assistant" or navigate directly to /wizard. (The dashboard's "New project" button opens the quick form without the assistant.) The wizard has six steps:
- Pick the target platform. Web.
- Pick the backend. Modern Spring Boot Backend.
- Pick the frontend. For this quickstart no frontend is fine.
- Answer questions. Use sample values:
- Project title: My first backend
- Vision: A simple health-check service
- Java version: 25
- Base package: io.example.health (required)
- Database: H2 (tests only) or none
- Architecture: layered
- Language: English
- Pick quality gates. Leave the ArchUnit toggle on, switch the others off.
- Summary. Confirm with "Create and edit project" — the page shows a cost estimate and prompt preview.
You now land in the project editor at /projects/<id>/edit with all fields pre-filled. Click "Save"; on the project page then click "Generate Markdown artifacts" to have the platform produce the six specification files (PROJECT.md, INSTRUCTIONS.md, AGENTS.md, WORKFLOW.md, DEFINITION_OF_DONE.md, README.md).
6. Watch the run
On the project page click "Create run". On the run-creation page:
- Run title: Create skeleton
- Goal: Set up the initial Maven project with Spring Boot, a health endpoint and a first smoke test
- Adapter:
mock(deterministic, no API key required) - Click "Create"
The run is now in status DRAFT. Click "Mark ready", then "Start run". Before the EXECUTION phase the run stops in WAITING_FOR_APPROVAL (setting run.approval-vor-merge, on by default): review the inline diff and click "Approve and continue". On the run detail page you see:
- Status indicator: moves through the seven phases
INTAKE→PROMPT_ASSEMBLY→WORKSPACE_PREPARATION→EXECUTION→VALIDATION→CORRECTION→COMPLETIONto the final stateCOMPLETED. - Logs (live): under "Show logs" every line the mock adapter emits appears immediately. The mock only simulates the run and writes no code; without a
pom.xml,VALIDATIONis skipped. - Git status: under "Git status" you see branch, HEAD, working tree and the latest commits — with the mock only the factory's commits with the Markdown artifacts.
7. Quality gate
Once the run reaches COMPLETED, click "Quality gate" and there "Run quality gate". The platform launches the six reviewers (architecture-reviewer, hallucination-reviewer, security-reviewer, dependency-scan, aider-review, claude-review) and shows the verdict:
- PASSED: all green, no findings.
- WARNING: some findings, but nothing blocking.
- FAILED: at least one blocking finding (e.g. an ArchUnit violation).
- SKIPPED / ERROR: reviewer skipped (e.g. missing CLI such as
aider) or crashed / a mandatory policy requirement not met — never a silent pass.
For each reviewer you see findings with severity, confidence score and explanation. In the quickstart with the mock adapter you should typically get PASSED — mock outputs are designed not to trigger real violations.
/einstellungen → Quality gate: advisory (default) only records, blocking starts the correction loop.
The full SDLC loop
What you just stepped through above is a slice of the full lifecycle the platform runs iteratively. Once set up, the loop closes on its own — each pass leaves the project a little more finished:
- Plan. A plan run analyses the project and produces planning files (
plans/*.md) that show up as a backlog — a prioritised list of concrete work items. - Select. You activate a backlog item as the next goal.
- Build. A build run works the item on its own branch (
sdlc/run-…) in the persistent workspace — the main line stays untouched. - Self-correction. If the build fails (red test, compile error), the agent automatically retries with the error feedback — capped at two automatic attempts.
- Quality gate. The reviewers check the result. The mode is selectable: off, advisory (findings are shown but don't block) or blocking (findings stop delivery).
- Deliver. With a Git remote and GitHub token configured, the platform pushes the branch and opens a pull request. Without a remote it falls back to a local merge.
- Learn. Insights from the run flow into project memory and are available to follow-up runs as context.
- Onward. Optionally the platform offers auto follow-up proposals (a fresh plan run) — and the loop closes.
/einstellungen. In the quickstart with the mock adapter you can dry-run the loop once; with real adapters (step 8) it produces production commits.
Cleaning up
To stop the platform without losing data:
docker compose down
That keeps Postgres data in the Docker volume. The next docker compose up -d brings your account, projects and runs back.
To wipe everything (DB, workspaces, logs):
docker compose down -v
-v flag deletes all Docker volumes, including your database. Only do this if you really want to start over.
Common questions
Port 8080 is already in use
Set SOFTWAREFABRIK_APP_PORT=9090 in .env and restart the containers. Alternatively, stop the process holding 8080 (often Tomcat or another Spring Boot process) — find it with lsof -i :8080.
Login page rejects the password
Check that the password in .env is spelled correctly (no quotes, no leading/trailing whitespace). With docker compose logs app | grep -i admin you can see whether the platform created the bootstrap admin. If you get a Whitelabel Error Page instead of the login, the app is usually still starting — wait a minute and reload.
Build takes ages
The first Maven build takes 2–4 minutes pulling Spring Boot dependencies. Subsequent builds are much faster thanks to the Docker layer cache. Use docker compose build --pull to force a clean build if you suspect a corrupted cache.
Wizard shows outdated versions
The version cache refreshes daily at 03:00. On a fresh setup it has no values yet and shows fallback versions from the code. At /einstellungen/wizard/versions you can hit "Refresh now" — needs an internet connection.
My run is stuck in DRAFT
A new run is always in DRAFT. You first need to move it to READY and then click the "Start run" button. Two confirmation points by design — to prevent accidentally burning tokens.
Where do workspaces live?
With Compose in the Docker volume workspaces (inside the container under /var/lib/softwarefabrik/workspaces), with a native start under ./workspaces. You can change the path at /einstellungen → Workspace. Each project has a persistent workspace there (<project-slug>/workspace/) with its own Git history; follow-up runs continue in it.
Choose the operating mode
Before switching to real adapters, decide the instance's operating mode. It controls whether the subscription login (personal Claude/Codex plan) is allowed or whether only API keys are used. Set it as the betrieb.modus setting under /einstellungen (or via env SOFTWAREFABRIK_BETRIEB_MODUS):
EINZELPLATZ_ABO(default) — uses the Claude/Codex subscription login (personal Max/Pro plan). Convenient for a single seat, no API billing setup needed.TEAM_API_POOL— disables the subscription login and enforces API key mode (team/pool billing). The factory does not check whether a key is actually present: for Claude Code,ANTHROPIC_API_KEYin the environment of the factory process or a key stored on the integrations page is enough (from 0.41.1; the environment takes precedence). Required as soon as more than one person uses the instance: a Claude subscription is intended for personal use by the subscription holder.
EINZELPLATZ_ABO is fine. It only matters once you use real vendor adapters (next step).
8. Onward with real adapters
Once the mock adapter works, the vendor adapters are next:
- → Tutorial with Claude Code — full workflow against Anthropic.
- Set up API keys:
/integrationsin the platform UI. In API-key mode the agent adapters inject the keys stored here when the factory process environment has none (Claude from 0.41.1; Codex, Gemini, Kimi and Aider from 0.41.2). The environment takes precedence. - Activate container sandbox: setting
execution.sandbox.variant=containerin/einstellungen.