Quickstart · v0.44.0 · 10 minutes

To your first run in 10 minutes.

This page takes you from the unpacked bundle to first run completed in ten minutes. Click by click, no prior knowledge needed, with mock adapter (no API keys required).

~10 min just Docker Mock adapter · no cost no prior knowledge

Prerequisites

You need just three things on your machine:

  • Docker (24+) and Docker Compose v2 — verify with docker --version and docker 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.
Note: You do not need to install Java, Maven or Node locally — for this quickstart all builds run inside containers. If you later use real vendor adapters such as 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 }))
Important: If you omit 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 in SOFTWAREFABRIK_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.

localhost:8080
The Software Factory dashboard after login
The dashboard after login (German UI). The yellow "Mock adapter active" banner is intentional — in the quickstart everything runs against the mock, so at no cost.
Hint: If you don't see the login page and instead get the Whitelabel Error Page: wait another minute (the app is still starting) and reload. If the login form appears but rejects the password: check the logs with 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:

  1. Pick the target platform. Web.
  2. Pick the backend. Modern Spring Boot Backend.
  3. Pick the frontend. For this quickstart no frontend is fine.
  4. 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
  5. Pick quality gates. Leave the ArchUnit toggle on, switch the others off.
  6. Summary. Confirm with "Create and edit project" — the page shows a cost estimate and prompt preview.
localhost:8080/wizard
The project assistant starting a new draft
The assistant walks you through your first project in six steps — target platform, backend, frontend and the matching questions.

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).

Tip: Read the artifacts once before launching the first run — they're editable and they're what the agent reads as its brief. Typos or fuzzy phrasing show up later in the commits.

6. Watch the run

On the project page click "Create run". On the run-creation page:

  1. Run title: Create skeleton
  2. Goal: Set up the initial Maven project with Spring Boot, a health endpoint and a first smoke test
  3. Adapter: mock (deterministic, no API key required)
  4. 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 → COMPLETION to the final state COMPLETED.
  • 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, VALIDATION is 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.

Policy tip: lenient (default) blocks only CRITICAL, strict blocks HIGH and CRITICAL and requires security and architecture review. Whether a FAIL holds up the run depends on the mode at /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:

  1. 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.
  2. Select. You activate a backlog item as the next goal.
  3. Build. A build run works the item on its own branch (sdlc/run-…) in the persistent workspace — the main line stays untouched.
  4. Self-correction. If the build fails (red test, compile error), the agent automatically retries with the error feedback — capped at two automatic attempts.
  5. 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).
  6. 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.
  7. Learn. Insights from the run flow into project memory and are available to follow-up runs as context.
  8. Onward. Optionally the platform offers auto follow-up proposals (a fresh plan run) — and the loop closes.
Note: You start the plan run in the project under Backlog / Plans, enter the Git remote on the project page and the GitHub token under Administration → Integrations; quality-gate mode and auto follow-up proposals are set at /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
Caution: The -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_KEY in 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.
Note: For this quickstart with the mock adapter the operating mode is irrelevant — the default 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: /integrations in 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=container in /einstellungen.