Aleph

Build with Git

Git is the recommended way to build and maintain Aleph agents. The starter repository includes a working weather agent, supports multiple agent folders, and publishes changes from GitHub Actions.

Create your repository

Use the Aleph agent starter template, or clone it:

git clone https://github.com/gubkin-labs/aleph-agent-starter.git
cd aleph-agent-starter
pnpm install
pnpm setup

pnpm setup replaces each template manifest ID with a fresh permanent UUID. Commit those generated agentId values. Aleph uses them to update the same agents on future syncs, and rerunning setup leaves initialized IDs unchanged.

Customize the agent

Open agents/weather/. Start with AGENTS.md for behavior and README.md for the human-facing explanation, then adjust runtime configuration, hooks, schedules, and skills as needed.

Keep credentials out of the repository. Declare required names in sandbox.toml, then store their values in the matching Aleph Vault or Variables scope. Connect Discord and Telegram from the Channels page after publishing.

Publish on push

Create a user or organization API key from Settings → API keys. Add it to the GitHub repository as an Actions secret named ALEPH_API_KEY. The included workflow uses the production Aleph API by default; add ALEPH_API_URL only for another environment.

Commit and push to main. The workflow validates and synchronizes all agent folders. New agents are published disabled so you can inspect their requirements and choose when to enable them.

Add another agent

Copy agents/weather/ to a new directory, change its manifest metadata, set agentId to TEMPLATE, and run pnpm setup again. Each directory under agents/ with an aleph.json is synchronized independently.

Removing a previously synchronized folder archives its Aleph agent. Treat the repository as the source of truth.

Pull remote changes before pushing

When self-modification publishes a newer Aleph version, the next Git sync may stop at the version gate. Pull the complete remote version before publishing another Git change:

pnpm dlx @gubkin-labs/aleph-cli@latest agents pull agents/weather

Review and commit the downloaded bundle and stamped versionId. Do not edit versionId alone; it records which remote version the Git tree actually contains.

Continue with Bundle structure to understand every file in an agent.