Entwurfswerk

A local-first collaborative workspace for people and software actors. The primary interface is an infinite spatial canvas, and every addressable participant is an actor.

Workspaces hold documents, nodes, agents, scripts, data, charts, and workflows. Actors exchange typed messages and signals. The whole workspace has a deterministic Markdown representation, so it imports, exports, and diffs in Git.

Downloads · Workspace Markdown · API reference

What makes it different

• Local-first. No Entwurfswerk cloud is required. The local database is the operational source of truth.
• Portable. A workspace is a .dw.md document: readable, diffable, and recoverable without the application.
• Programmable. QuickBEAM runs trusted script actors inside the BEAM with explicit capabilities instead of unrestricted access.
• Schedulable. Agents create durable waits and recurring schedules; delayed work survives restarts.
• AI without lock-in. Bring your own keys or models: hosted providers, local endpoints, or in-browser models.

Editions

The edition is a build property. A free build contains no Pro code at all, because Pro is a separate application linked into the binary only for Pro builds.

A lapsed licence downgrades capabilities, never data access: every workspace stays openable, exportable, and recoverable.

Developers

• API reference — generated from the source with ExDoc.
• The workspace Markdown format is documented in Workspace Markdown.
• Scripting with QuickBEAM, the HTTP interfaces (JSON:API, GraphQL), and the generated AshTypescript client are documented here as they land.

Working in the repository

The repository carries internal material that is deliberately not published here: architecture notes, decision records, task definitions, and operations runbooks live under docs/. Start with AGENTS.md and docs/agent/START_HERE.md in the repository.

Downloads

Releases come from the GitHub releases page. Every release is built from the same commit for both editions, and the free edition tarballs are attached to the release directly:

Pro artifacts are not published there: a Pro build is a different binary with a licensing gate, so it travels through its own channel. The free tarballs are complete applications; nothing in them is disabled at runtime.

Running a release

tar -xzf entwurfswerk-<version>-<target>-free.tar.gz
_build/prod/rel/<release>/bin/<release> start

Then open http://localhost:4000.

rel/env.sh.eex supplies what the release needs to boot without extra setup:

• DATABASE_PATH defaults to $ENTWURFSWERK_HOME/entwurfswerk.db ($HOME/.entwurfswerk)
• SECRET_KEY_BASE and TOKEN_SIGNING_SECRET are generated on first start into $ENTWURFSWERK_HOME/secrets.env, outside the database
• the HTTP endpoint serves by default; ENTWURFSWERK_SERVER=0 boots without it

Every value can be overridden from the environment.

Portable workspace Markdown v0

This format is an import and export representation. It is also an agent-readable context representation. It is not the pointer-rate runtime database.

Use ordinary Markdown plus fenced code blocks. Use YAML as the serialization language for Entwurfswerk metadata. Use the second info-string token as the semantic type.

Example:

# Checkout workflow

```yaml ew/actor
id: payment
kind: node
name: Payment
position: [480, 220]
```

```yaml ew/actor
id: ada
kind: agent
name: Ada
runtime: local
```

```yaml ew/message
id: 01KEXAMPLE
from: ada
to: payment
type: comment
body: Check the retry policy.
```

Initial fence types

Keep the initial type set small.

yaml ew/schema
yaml ew/actor
yaml ew/message
yaml ew/snapshot
typescript ew/script

YAML profile

Use a restricted JSON-compatible YAML profile. Do not use anchors, aliases, custom tags, or executable YAML types.

Determinism rules

Use stable block identifiers. Use stable key order. Use stable block order where semantics permit it. Avoid generated timestamps unless the timestamp is semantic data. Preserve unknown fields during round trips. Preserve unknown typed fences during round trips. Preserve ordinary Markdown during round trips.

Diff rule

One logical change must create a local textual diff where practical. A node move must not reformat unrelated blocks.

Runtime mapping

Import parses Markdown into semantic data. The importer validates Entwurfswerk fences against schemas. The importer applies changes through Ash Actions or a trusted import transaction.

Export projects current workspace state into deterministic Markdown.

API reference

The module documentation is generated from the source with ExDoc and published under /api/.

Open the API reference

Interfaces

The table describes what exists in the current release. Scripting and the HTTP interfaces are documented here as they land, and nothing in it is a promise of a date.