Aleph

Validate and publish

Publishing turns the current files into an immutable version. Validation catches structural and configuration problems before that version can run.

Pre-publish checklist

  1. Include all five required root files.
  2. Keep AGENTS.md and README.md non-empty.
  3. Parse every TOML file and check its accepted fields.
  4. Use only safe relative paths.
  5. Keep schedule intervals at one hour or longer.
  6. Use qualified secret and variable references.
  7. Remove credentials and private data.

Publish a version

Upload the complete bundle or edit supported files in Aleph. The platform validates paths and configuration, then creates an immutable version when the set of file paths or their bytes changed. Re-publishing an identical bundle returns the latest version without adding a duplicate; messages, timestamps, and file ordering do not make content different.

For Git synchronization, aleph.json must contain a permanent UUID agentId. First sync creates that exact identity and later syncs update it. Optional UUID versionId records the base version the Git tree last absorbed or published. Push and sync read only its file hashes and upload added or modified bytes. Aleph preserves unrelated newer remote changes, such as runtime-written memory, without requiring a pull. If local and remote changed the same file, push reports a conflict; pull and resolve it before publishing. An existing remote with versions but no local versionId requires one initial pull. After a successful push or sync, the CLI stamps versionId from the uploaded or reused version. The manifest's remaining catalog metadata participates in change detection, so editing it creates a new version even when runtime files are unchanged. Changing only agentId or versionId does not count as a version change. The local .aleph/state.json cache is not an identity fallback.

Review before enabling

Publishing and enabling are separate. Inspect the new version, confirm its configuration requirements and schedules, then enable it to pin that version.

For catalog Git sync with --no-enable, only newly created agents start disabled. Existing agents keep their enabled or disabled state; if an agent is already enabled, sync repins it to the new Git version without disabling it. If an existing agent was deleted, sync creates it again so a present Git folder returns it to the catalog.

Public visibility makes the agent discoverable and its bundle inspectable. It does not bypass validation or copy secret values to consumers.

Installed agents cannot publish bundle changes. The source owner controls the live harness; choose an independent clone when you need to edit files.

Publish a Git repository

The Aleph agent starter includes a multi-agent directory layout and a push-to-main GitHub Actions workflow. Run pnpm init-agents once after creating a repository so every template manifest receives a unique permanent agentId, then commit those IDs.

Add ALEPH_API_KEY as a GitHub Actions repository secret. The workflow uses the production API unless the optional ALEPH_API_URL secret is set, and synchronizes every discovered folder under agents/ with --no-enable.

Set icon in aleph.json to a local JPEG, PNG, or WebP cover (maximum 5 MB). The CLI uploads it to Aleph, so the Git repository does not need to be public. Use iconUrl only when you intentionally want an externally hosted image.

Run aleph agents pull when you want newer remote files locally or push reports a same-file conflict. You do not need to pull unrelated remote changes before pushing. Pull updates bundle files and versionId together; do not edit only versionId by hand.