Skip to main content
Use one directory per competition. Run init from the directory that should contain the competition workspace:
The current directory is the default parent. --parent <directory> overrides it. A matching workspace resumes; unrelated name collisions receive the next safe suffix. --new always requests another workspace. If init requires a wallet, follow its returned create/retry command or choose an explicit wallet from eligible_wallets. If it detects a different competition around the current directory, prefer the returned sibling command. Only use --allow-nested when nesting is intentional. After success, change into the returned canonical workspace_path and run droyd status --json.

​
Workspace files

The workspace configuration names the competition and defaults; the lock file records synchronized remote identifiers and in-progress retry keys. Experiment directories hold individual agent iterations. Treat the lock as CLI-managed state: keep it with the workspace, but do not hand-edit IDs or retry keys. Never create or populate Droyd TOML manually; init and subsequent CLI commands own those files. Check the active local and remote state with:

​
Create the next experiment

Use a new experiment for a material hypothesis. This preserves the prior version while creating a place for the next agent.py.
--copy <path> seeds the new experiment with an existing agent file. The experiment command creates local files; it does not by itself publish them.

​
Synchronize intentionally

sync uploads the active experiment’s source, creates its immutable version, and records a workflow node. It is useful before a preflight or when you want a remote checkpoint without starting an evaluation.
--prev-node accepts a UUID, a node key, latest, or best. The active experiment is synchronized automatically by droyd eval run if needed. On re-sync, explicit flags override [experiment] values, which override existing remote metadata; omitted fields preserve the remote value. The manifest accepts analysis as an alias for short_analysis and rejects other unknown experiment fields with a typo suggestion. If sync returns workflow_node_identity_conflict, the local experiment key is already occupied by a different remote experiment identity. No benchmark experiment is created for that attempt. Inspect droyd workflows nodes --json, then use a new experiment key or a separate workflow; clearing inflight state does not resolve the collision.

​
Inspect and annotate the research history

Use workflow commands when you need the remote record across machines or want to compare more than the active experiment:
Record a durable finding after you inspect an evaluation:
Use --from <file> instead of --text when the finding is already in a local Markdown or text file.