Quickstart

Dots runs on your infrastructure, and your coding agent is what puts it there. You paste one prompt into Claude Code or Codex, answer a few questions, and end with a running instance holding your own knowledge.

The IAGREED plugin arrived with your purchase and already carries both skills, so nothing has to be installed first. There is one prompt per agent, and they differ only in how that agent invokes a skill. Pick the one for the agent you use and paste it whole.

The path is two skills. /setup brings an instance up on the posture you choose and proves it answers; /onboarding fills it with your own machine. Setup configures nothing about your workspace, and onboarding assumes an instance that already answers — the health probe is the handoff between them. Four decisions are yours to make: which posture, your license key, which coding-agent transcripts may be read, and which repository goes into the code graph.

Claude Code

Open Claude Code in any project directory and give it this:

You already have the IAGREED plugin. Take me through Dots first run with it.

1. Run the /setup skill. Ask me which posture I want (Railway self-host, Docker
   self-host, or the bare local daemon) and prompt me for my license key.
2. Setup is not done until the health probe returns ok, the license validates,
   and an authenticated row read succeeds. Show me that output.
3. Then run the /onboarding skill: detect the coding agents on this machine,
   take my consent per source, bind my folders and repos, and ingest my repo.

No install step precedes that prompt, and the persistent changes both skills can make are listed below.

Codex

Codex holds the same plugin and the same two skills; only the invocation differs. They are reached as $iagreed:setup and $iagreed:onboarding rather than /setup and /onboarding, so the prompt below is the Claude Code one with that single change.

Open Codex in any project directory and give it this:

You already have the IAGREED plugin. Take me through Dots first run with it.

1. Run the $iagreed:setup skill. Ask me which posture I want (Railway self-host, Docker
   self-host, or the bare local daemon) and prompt me for my license key.
2. Setup is not done until the health probe returns ok, the license validates,
   and an authenticated row read succeeds. Show me that output.
3. Then run the $iagreed:onboarding skill: detect the coding agents on this machine,
   take my consent per source, bind my folders and repos, and ingest my repo.

What The Skills Change

Both skills make durable changes only where you authorize them. A hosted posture can create or configure infrastructure in your account; the bare local daemon writes its data plane under ~/.dots/; and the setup helper creates a stored credential for the origin you chose. During onboarding, consent decisions are saved on that instance, a local binding watches each selected folder or repository, and a consented repo ingest writes graph rows and edges there. The flow does not rewrite source files in the project where you invoked it, and it does not install a second plugin or a standalone dots-setup distribution.

Have your license key to hand before the setup step. Your instance validates it once, against the hosted license authority, and stores the resulting credential itself.

Pick Where Dots Runs

Setup asks this first, because it decides where your data lives. Three postures ship, and these three are the whole list:

• Railway self-host — your own Railway project, with a URL other people can reach. deploy/self-contained/railway.json declares the same app, worker, and bundled-Postgres capability as the container stack, but it brings no object store of its own: storage is yours to supply, and the secret-bearing variables are set in the Railway dashboard rather than committed.
• Docker self-host — the whole stack on one machine or server you control, from deploy/self-contained/docker-compose.yml. Postgres, object store, and identity plane are bundled; nothing external is required, and no configuration is needed to boot. On first boot a one-shot secrets service generates the database password, the session-signing secret, the workspace company id, and the object store's credentials into a persistent volume, and a one-shot init service applies migrations and provisions the bucket. You open http://localhost:3000 and sign up, and the first signup becomes the owner.
• Bare local daemon — one machine, no containers, no public origin. The smallest thing that works. dots local start runs the same multi-tenant API over a supervised PostgreSQL 18 on 127.0.0.1:3687, with its data plane under ~/.dots/: postgres/ for the database, files/<companyId>/ for uploads, and daemon.lock and daemon.log for lifecycle state.

Each posture serves the same API with real accounts and real companies. The loopback bind of the local daemon is a network posture rather than a trust boundary — every request is still authenticated. The local daemon boots unprovisioned, with no owner and no company, until the first one is created.

Self-host Dots covers each posture's environment in full, including bringing your own Postgres or storage. Setup walks the posture you choose and quotes every value from the file that defines it, so reading that reference first is optional.

How Setup Proves It Worked

Setup finishes on a fixed three-part proof your agent shows you, rather than on an exit code.

First, GET <origin>/api/v1/healthz returns 200 with {"data":{"status":"ok"}}. Second, a completion helper signs the owner in without exposing the password or the session bearer, validates your license against the hosted authority, stores the resulting credential, proves an authenticated Memory Bank read, and records the truthful deploy mode, license result, and workspace state on the instance. Third, dots rows list memory-bank --limit 1 succeeds independently against that same origin using the stored credential.

All three have to land. A green health probe alongside a rejected license, a failing row read, or a failed state write is not a finished setup, and the skill reports it as unfinished rather than green.

The license is validated by the hosted authority rather than by your own instance, so that one step needs outbound network access even on a posture that is otherwise entirely local. The key never goes into a command argument: the helper prompts for it with terminal echo disabled, or reads it from a one-shot credentials file that it deletes afterwards, so it stays out of your shell history and your process list.

Check The Instance Yourself

These are ordinary reads against the instance you just brought up:

dots local status
dots dotabases list
dots rows list memory-bank --limit 1
dots onboarding state get

dots local status applies to the bare-daemon posture. It always exits zero and reports the record — running or not, the port, the home directory, and whether the process holding that port is really the daemon — so read its output rather than its exit code. dots dotabases list shows what your workspace holds; it is a survey read, so it answers at the summary disclosure level and closes with a footer naming that tier. Every field these checks read — the name and slug of each Dotabase, the id of each row — is identity, so the narrower --level scan serves them too, while --level full widens any survey read to the whole record when you need a description, an id prefix, or a stored schema. The Memory Bank read is the same one setup used as its third proof. And dots onboarding state get returns { complete, answers }, where answers is null until the first step records something — the honest report of an instance that is up but not yet filled.

Then Hand Off To Onboarding

A running instance holds no knowledge of your own yet. The onboarding skill fills it, in four steps:

1. Detect which coding agents this machine carries.
2. Consent, per source, before a single transcript is read.
3. Bind the folders and repo checkouts that should keep flowing in.
4. Ingest your repo into the code graph.

The order matters: consent gates every read, so it comes before any sync or ingest.

Detection is a filesystem probe rather than a question. Three agents are supported — Claude Code, Codex, and Cursor — and each is looked for at its session root: ~/.claude with projects/ beneath it, ~/.codex with sessions/, and Cursor's OS-dependent application-support directory. A root that exists and holds sessions is a detection; a root that does not exist is not. Every absent agent gets a stated install pointer rather than a silent skip, and a machine carrying no agent at all still finishes the journey.

Consent is per folder, not per machine. One agent commonly carries several session folders, each with its own source key of the form <platform>:<folder-hash>. Running dots coding-agents sync with no consent flag refuses by design and names every detected key on its way out, without reading a single session byte — that refusal is how the list you are asked about gets produced. You answer for all of them, for a named subset, or for none, and the decision is stored on your instance rather than on this machine. The gate fails closed: absence of a decision is never consent, and an unreachable instance refuses the run instead of degrading into an open one.

A binding is a source that keeps syncing without being asked again. A markdown folder lands rows in a Dotabase you name, a repo checkout keeps the code graph current, and a connector resource pulls from a connection your workspace already has. A local binding watches by default and runs on a daily cadence. There is no unbind: dots sync pause --id <uuid> is the only stop, which is why the step sweeps the existing bindings before it creates another.

The repo ingest is not the same as binding a repo. The bind keeps the graph current; the guided ingest builds it the first time. Its consent is bound to the resolved absolute path, so a consent captured for one checkout can never drive an ingest of another, and without that flag the wrapper performs no ingest at all. The run streams progress as one JSON object per line — the resolved path, the ingest start, row counts, edge counts, a finalize total, then a terminal result. A large repository's first ingest takes a while, and the guided form waits for that terminal result rather than returning early.

What Onboarding Records

Every step's outcome is recorded on the instance rather than on your machine, and read back with dots onboarding state get. The recorded keys are few: which agents were detected and offered an install, whether a repo was ingested and where, and a single completedAt timestamp.

Consent and bindings are not recorded there. Consent is authorization rather than an answer, and it lives on the instance as a per-folder decision the sync family re-reads on every run. A binding is already its own durable record, listed by dots sync list and readable one at a time by id. Neither needs a second copy in the answers.

completedAt is written once at the very end, and it is the only key that flips complete to true. The journey is resumable on that key: you can stop after any step, and onboarding reads what is already recorded and re-enters at the first step whose answers are missing rather than starting over.

Next

You now have your own Dots instance, onboarded against your own machine. For the guided build of a Dotabase from scratch — rows, edges, and viewing them as a graph — follow Your First Dotabase.

The instance already holds content to read: the Memory Bank you read during setup was seeded by workspace provisioning, and the transcripts from every source you consented to are already imported, with the per-source imported, skipped, and failed counts printed by the sync that brought them in. Self-host Dots is the reference for the environment behind whichever posture you chose, including replacing bundled Postgres or storage with your own.