Your agent.
A shared direction.

Prepare your tools

Install Node 24 and Git. Download a checkout of the Artyfact source, then run the following from its root. npm links the local CLI into the workspace.

npm ci
export PATH="$PWD/node_modules/.bin:$PATH"
npx --no-install artyfact --help

The PATH step saves the source checkout's absolute CLI location for this terminal, including after you enter the fork. --no-install uses that CLI without fetching an unrelated package from the registry.

Get a Realization

In the platform's Work view, choose an Evolution and start work. An authorized operator starts the Realization. The response supplies your IDs, a fork token, a Realization secret and a generated start command.

The ARTYFACT_TOKEN authorizes Git access to the fork. The ARTYFACT_SECRET authorizes that Realization's platform calls. Neither is the operator's Cloudflare API token or admin credential.

Read the two values from the Start work response into your shell without putting them in command arguments or history:

read -rs -p "Fork token: " ARTYFACT_TOKEN; printf "\n"
read -rs -p "Realization secret: " ARTYFACT_SECRET; printf "\n"
export ARTYFACT_TOKEN ARTYFACT_SECRET

This snippet uses Bash. Your shell or secret manager may provide another secure way to set environment variables.

Set ARTYFACT_PLATFORM to the platform origin supplied by the operator. For the hosted demo, use https://artyfact-platform.dawka.workers.dev. The CLI uses --platform, then ARTYFACT_PLATFORM, then ARTYFACT_URL. With none set, it looks for an Artyfact platform on localhost:1337 through localhost:1346; if none identifies itself, it stops. Use the real IDs from Start work in place of the placeholders:

npx --no-install artyfact start <realization-id> \
  --system <system-id> --evolution <evolution-id> \
  --dir ./my-realization

Give the agent its packet

Open the new workspace with your preferred agent. The CLI creates TASK_PACKET.md and an AGENTS.md instruction block. The packet contains pinned intent, relevant model excerpts, acceptance criteria, permitted and protected paths, commands and concurrent work.

Read TASK_PACKET.md fully. Realize the scoped change, preserve its commitments, use the prescribed checks, and checkpoint what changed and what remains.

Use the terminal you prepared above for the commands below. In a new terminal, repeat the PATH setup from the Artyfact source root before entering the fork.

The Git token stays in your environment. The CLI saves the Realization secret in an owner-only, Git-excluded .artyfact.json; do not publish or share that file.

Author reusable Parts

A Thing can start with its Genome alone. When reuse helps, create a package from a directory containing genome/ and optional app/, or extract selected content from a Thing revision. Recipes pin exact package versions, name each contribution, and declare replacements for overlapping files.

artyfact parts create --id part.my-app --version 1.0.0 \
  --name "My app" --source ./thing --out ./part.json --apply
artyfact parts validate ./part.json
artyfact parts extract ./extraction.json --out ./extracted-part.json
artyfact parts compose ./recipe.json --out ./composed-thing
artyfact parts upgrade ./next-recipe.json --from ./composed-thing

These authoring commands preview by default. Add --apply to save files; validate reads an existing package. Composition saves genome/, app/ and a provenance baseline in .artyfact/. Upgrades preserve customizations or report conflicts without writing.

Inspect package and recipe commands before execution. Run them locally only with both --apply --run-commands; Genome loading never executes them. To publish a validated package to the configured catalog, preview artyfact parts publish ./part.json, then add --apply when ready. System-private recipes use --system <system-id> with an authorized operator.

Accept the Genome through review before starting the application Realization. Composition and publication do not deploy an application; deployment remains a separate authorized action.

Checkpoint and submit

From the Realization workspace, record progress and inspect status:

artyfact checkpoint "Implemented the scoped change; remaining checks noted"
artyfact status

When the candidate is ready, keep ARTYFACT_TOKEN available in this terminal and submit:

artyfact submit

Submission commits pending changes, pushes to the fork recorded in the workspace, and submits the exact candidate to the platform. A checkpoint or an agent's own report is not a passing Evaluation.

Review the evidence

Inspect the candidate's changed subjects, evaluations, conflicts and provenance. Checks that did not run remain unknown. The example's semantic provider may be a labelled fake; it does not establish real model performance.

An authorized reviewer decides whether to reject, revise or promote. Genome amendments require explicit acceptance. A promoted System revision and a deployed application are separate states.