Soul

The soul is your instance's configuration, stored as a git repository. It holds the definitions that make your TulipFarm what it is: resource schemas, agents, and skills. A fresh instance creates the soul at ~/.tulipfarm/soul, controlled by the SOUL_PATH environment variable.

You rarely touch the soul directly — agents write to it when you build by chat. This page is about what that store is and how it behaves.

Why a git repository

TulipFarm treats the soul as a configuration database that happens to sync over git. That choice buys three things at once:

History is the audit trail. Every change to an agent or schema is a commit. You can see what changed, when, and why, with ordinary git tooling.
Agents and humans edit the same store. An agent that creates a resource type writes the same schema.yml you would write by hand, then commits it.
Durability and portability. Point the soul at a remote and your configuration is backed up and movable between machines.

What lives in the soul

The repository has a fixed layout:

soul/
  resources/{name}/    schema.yml (+ optional hooks.ts)
  agents/{name}/       AGENT.md
  skills/{name}/       SKILL.md (+ references/)
  routines/{name}/     routine definitions
  integrations/{name}/ integration config
  llm.config.yaml      LLM provider tiers
  guardrails.yaml      input / tool-call / output guard rules
  soul.yaml            root manifest
  skills-lock.json     installed-skill provenance

Records, knowledge, and chats are not in the soul — those are data, and they live in the datastore.

How the soul syncs

The soul is loaded into the runtime at startup. If you set SOUL_GIT_REMOTE_URL, the instance clones the remote on first boot and pulls from it on a periodic schedule; main wins when histories genuinely diverge, but local commits that are merely ahead and un-pushed are preserved and retried, never discarded. Setting the remote from the setup wizard instead syncs immediately — no restart required.

With no remote set, the soul is local-only. Writes still commit locally, and your configuration is captured by backups of the soul directory.

Setting a remote is strongly recommended. It turns your soul into a backed-up, portable record of your whole instance.

Commit authorship

Soul commits are attributed to tulipfarm-bot <tulipfarmhq@gmail.com> by default — that's the author on every write regardless of whose credential authenticates the push to the remote. Override it with the BOT_GIT_NAME and BOT_GIT_EMAIL environment variables if you want soul history attributed to your own name or organization instead.

Soul writes are never gated

Editing the soul — creating an agent, a schema, or a skill — is a direct write and commit. There is no approval step. The git history is the review record.

This is distinct from what an agent does at runtime. When an agent takes a real-world or data action, that can be gated by its autonomy level. The rule is: soul = database, no gate; actions on the world = gated. Do not conflate the two.