Download all docs

Recipe: Bootstrap a Personal Circle

This recipe is the first one — before you build anything inside Triform, you need the thing everything lives inside: a circle. A circle is your tenant, your identity, your private database, your git repository, and your wallet, all at once. This recipe walks the bootstrap: how a personal circle comes into being, what you get for free the moment it exists, and the first elements you put in it.

The problem it solves

Most platforms make you assemble a workspace by hand — provision a database, wire up an auth layer, bolt on a secret store, create a repo. In Triform that assembly is one act: the circle. The moment you have one, you already have the isolated schema, the git history, and the wallet, with nothing left to wire. The trick is knowing that a circle is not created the way every other element is — it is bootstrapped through signing in, not through element creation.

Elements

ElementRole
circleThe tenant itself — your identity, isolated schema, git repo, and wallet.
app (or any frontend)The product-facing face you point the circle at, once you have one.
api-tokenA scoped credential for calling your circle’s operations from outside.
circle-refA pointer to a sub-circle, if you later grow into a tree of circles.

Flow

  1. Bootstrap the circle by authenticating — not by creating an element. A circle is the one type you do not POST into existence like a function or a table; it is minted when an identity first signs in. In a debug/dev environment the shortcut is POST /api/auth/dev with { "circle_name": "<name>" }, which auto-creates the circle if it does not exist. The name is the circle’s globally unique slug: 3–32 characters, lowercase letters, numbers, and hyphens, starting with a letter. Choose personal as the circle type for an individual (use organizational for a team or company).
  2. You now have a sovereign namespace — for free. The instant the circle exists it already carries the three things you would otherwise assemble by hand: a dedicated circle_{uuid} Postgres schema (data never leaks across circles), a git repository for version-controlled element storage, and a wallet holding your credentials, secrets, and AU balance. You provisioned nothing; the circle is all of them.
  3. Confirm what is inside it. GET /api/{name} returns the circle itself; GET /api/{name}/ (note the trailing slash) lists its children. A fresh personal circle lists empty — that empty list is the canvas you are about to fill.
  4. Add your first elements, flat. Everything you build sits flat directly under the circle — there is no library or folder wrapper. Create an action, a data element, a view; they compose by lookup and operation dispatch, not by nesting. (When you genuinely need a separate tenant later — a client, an environment whose data must never mingle — that is when you reach for a sub-circle, via the circle’s add_subcircle op, which mints a nested circle-ref.)
  5. Give the circle a face (optional). When you have a frontend or app element, point the circle at it with the circle’s set_frontend op so the circle has a product-facing entrypoint; unset_frontend clears it.
  6. Reach it from outside (optional). Mint an api-token for scoped programmatic access, and invite collaborators with the circle’s invite / members ops if the circle should not stay solo.

What this shows

The circle is the platform’s bottom turtle: it is simultaneously the identity you authenticate as and the boundary your data lives in, so isolation and identity are the same wall. An AI agent that signs in gets its own circle exactly as a human does — because the circle is the user, not a workspace the user owns. Bootstrap one, and every other recipe has somewhere to run.

Next pages