Installation¶
Prerequisites¶
| Requirement | Notes |
|---|---|
| Linux x86_64 | The pre-built binary targets Linux x86_64. Build from source for other platforms. |
| Claude CLI | npm install -g @anthropic-ai/claude-code |
| Claude authentication | Run claude once to complete the login flow |
Option A — Pre-built binary¶
Download the latest release binary and place it somewhere on your PATH:
# Download (adjust version)
curl -Lo craft-easy-agentic \
https://github.com/easy-software-system/craft-easy-agentic/releases/latest/download/craft-easy-agentic-linux-x86_64
chmod +x craft-easy-agentic
sudo mv craft-easy-agentic /usr/local/bin/
Verify:
Option B — Build from source¶
# Prerequisites: Rust stable, Node.js 20+, npm
git clone https://github.com/easy-software-system/craft-easy-agentic.git
cd craft-easy-agentic
npm install
npm run build # builds React frontend → dist/
cargo build --release --manifest-path src-tauri/Cargo.toml
# Binary: src-tauri/target/release/craft-easy-agentic
sudo cp src-tauri/target/release/craft-easy-agentic /usr/local/bin/
Register your first project¶
Craft Easy Agentic uses a project registry at ~/.config/craft-easy-agentic/projects.toml. Add projects with:
craft-easy-agentic project add petanque-life \
--repo ~/esi/petanque-life \
--name "Petanque Life" \
--color "#1A6B5A"
craft-easy-agentic project add airpark \
--repo ~/esi/airpark-ecosystem \
--name "Airpark" \
--color "#F39C12"
# Verify
craft-easy-agentic project list
Each project must have a tasks/BACKLOG.md file. See Framework Hub for project conventions.
Start the web dashboard¶
# Bind to all interfaces (required for LAN/mobile access)
craft-easy-agentic --serve 0.0.0.0:4242 --no-browser
On startup, the binary prints its access URL with a bearer token:
Token: b0dc712bbff77cd46660981ebccbe4c3
Open in browser:
http://127.0.0.1:4242/?token=b0dc712bbff77cd46660981ebccbe4c3
http://192.168.1.10:4242/?token=b0dc712bbff77cd46660981ebccbe4c3
Bookmark the LAN URL — it includes the token and works from any device on the same network.
systemd auto-start (recommended)¶
For a persistent, always-on installation use the included installer:
# From the craft-easy-agentic source tree
bash systemd/install.sh # default port 4242
bash systemd/install.sh --port 4242 # explicit port
bash systemd/install.sh --binary /usr/local/bin/craft-easy-agentic
The installer:
- Writes a systemd user unit to
~/.config/systemd/user/craft-easy-agentic.service. - Creates an env file at
~/.config/craft-easy-agentic/envwith a stable token that persists across restarts. - Enables and starts the service.
# Check status and get bookmarkable URLs
bash systemd/install.sh --status
# Uninstall (keeps config and registered projects)
bash systemd/install.sh --uninstall
Manual service management¶
systemctl --user status craft-easy-agentic
systemctl --user restart craft-easy-agentic
systemctl --user stop craft-easy-agentic
journalctl --user -u craft-easy-agentic -f
Token persistence¶
The bearer token is what protects the dashboard. It is printed on stdout at startup. If you use --serve without systemd, the token changes each restart.
With systemd, the installer writes the token to ~/.config/craft-easy-agentic/env:
The server reads this file at startup, so the token — and therefore your bookmarked URL — stays the same after restarts and reboots. The token is also persisted to $XDG_RUNTIME_DIR/craft-easy-agentic/token as a fallback.
Sync framework files into projects¶
After registering projects, sync the canonical runner script and templates:
craft-easy-agentic project sync petanque-life # one project
craft-easy-agentic project sync --all # every registered project
craft-easy-agentic project sync petanque-life --dry-run # preview only
This copies runner/run-backlog.sh, task templates, and the default runner-config.yml into each project's tasks/ directory. See Framework Hub for details.
Optional: enable host integration¶
Out of the box, claude --print subprocesses spawned by the systemd service inherit only a minimal environment — gh, az, kubectl, git push over SSH, etc. will silently fail in chat. The fix is one click in the dashboard:
- Open the dashboard
- Click the wrench icon in the topbar
- Click Aktivera on the Tools & Auth panel
This writes a passenv.conf drop-in for the systemd service and a ~/.bashrc.d/ snippet that imports your login shell environment. Full details in Tools & Auth.
Optional: multi-account rotation¶
To wire in a second Claude subscription for higher capacity (transparent rotation when one account hits the rate limit):
- Seed each account's credential directory with
claude /loginusingCLAUDE_CONFIG_DIR=<path>. - Register them in
~/.config/craft-easy-agentic/accounts.toml. systemctl --user restart craft-easy-agentic.
See Multi-Account Rotation for the full setup.
Optional: install inotify-tools¶
The runner uses inotifywait for sub-millisecond wake-up when a task lock is released. Without it, the runner falls back to a 2-second poll (still 15× faster than older builds, but slower than inotify):