Getting started

Sapient runs your company. You describe the product; a factory of AI seats — a Chief of Staff, a product manager, engineers, a designer, support, marketing, finance — specs it, builds it, ships it, and keeps it running. You approve the decisions that matter.

This is the documentation for everything you touch from the outside: the setup flow, the CLI, the connectors that let your factory reach your real accounts, and the two public APIs.

1. Get an account

Sapient is invite-only during the design-partner phase. Request access at sapient.works and you’ll get an email when a seat opens.

2. Create your factory

Sign in at app.sapient.works. First run drops you into an eight-step wizard — it takes a few minutes, and it’s resumable: close the tab and come back where you left off.

1. Are you building software? If not, tell us what you are building and we’ll skip the repository steps.
2. Existing repositories? Connect what you have, create something new, or decide later.
3. Product name and a one-line mission. One sentence. “A time-tracking app for design studios” is enough to start.
4. Structure. Monorepo or a repo per surface, and which surfaces exist — frontend, backend, iOS, Android.
5. Connect your code. Install the GitHub App on your org and pick (or create) a repository per surface. Nothing is pasted; see GitHub.
6. Set up your product spec. Either import from your codebase — the factory reads the repo you just connected and writes a spec from what’s actually there — or write one from a description. This is the step that matters most: the spec is the source of truth every seat works from, so everything downstream inherits its quality. Once a spec section is approved it becomes searchable by meaning to every seat, so an engineer picking up a story can find what you specified about rate limiting even if you wrote it down as throttling — and cite the exact section back to you. You can revise any section later in the product’s spec editor — a rich-text surface that renders the markdown as you read (headings, bold, links, lists, quotes, code), revealing the raw markers only where your cursor sits; a Markdown toggle shows the full source, and saving opens the product’s spec review.
7. Summary. Confirm the product, the structure, and the repositories.
8. Say hello to your Chief of Staff. Optional, and the best thing you can do next.

3. Work the setup checklist

Home shows a checklist of what your factory still needs to be able to finish work rather than just start it — a version-control connector, a deployment target, a database backend, billing credits, and enough seats. Each item links straight to the screen that closes it. A factory can run with gaps; it will tell you plainly what it can’t do because of them.

4. Talk to your Chief of Staff

The Chief of Staff is the seat you actually talk to. It’s the one that knows the whole company: what’s in flight, what’s blocked, what needs you. Open it from the drawer in any screen, or from the terminal:

sapient chat

Ask for things the way you’d ask a competent colleague — “what shipped this week?”, “get the signup flow working on mobile”, “why is the deploy stuck?” It routes work to the right seats and comes back to you when a decision needs a human.

Formatting in chat

Messages in the web app render Markdown — bold, lists, links, tables, and fenced code blocks — for your teammates’ replies and for what you write. Line breaks are kept as you typed them, so you don’t need blank lines between rows of a list.

Two things behave differently on purpose. Inline images are shown as a small “image” chip rather than loaded, so opening a message never fetches anything from a third-party server on your behalf. And HTML in a message is displayed as text, never run. Both apply to every message, whoever wrote it. The terminal (sapient chat) shows message text unformatted.

Changing who does what

Org chart is the roster. Open any seat to read its charter — the one paragraph saying what that seat is accountable for — and edit it; the charter goes in at the top of everything the seat does, so rewriting it is how you redirect a teammate.

The activation mode on each seat is its authority, and it only ever goes as far as you set it:

Mode	What the seat may do
Observe	Analyze and report. Takes no action outside the factory.
Draft	Produces real work, but nothing ships until you say so.
Execute	May send, publish, deploy and spend, inside its budgets.
Autonomous	Runs continuously, except for the classes that always need you.

Pause seat drops a seat to Observe and Resume returns it to Execute — useful when a teammate is doing the wrong thing and you want it to stop without removing it. Autonomous stays unavailable until the seat has an accountable owner: someone other than itself who answers for what it does unsupervised.

Add seat hires a new teammate. New AI seats start in Draft, so a seat you just created cannot ship anything before you have read its work.

5. Approve the things that need you

Some actions never happen without a human: deploys, spending, outbound email, pricing changes, legal, hiring, and product-spec changes. They collect in Approvals on the web, in the iOS app, and in sapient approvals list. Nothing sits in the dark — every card says in plain language what happened, what approving does, and what rejecting does. A chat instruction card quotes the instruction and names who asked; a code-review escalation says what the reviewer hit and what each button will do about it; and each card shows who it’s waiting on and for how long. Cards whose underlying work can no longer happen (for example, a chat instruction that expired unanswered) retire themselves instead of sitting in your queue.

Product-spec changes get there the same way the rest of the work does. When a conversation in team chat settles on a change to what the product does, your Product Manager writes it into the spec as a draft and it shows up here for review. Your agents can draft spec changes; only you can publish one, and approving it cuts a new version of the product.

Each document in a review can be read two ways. Changes shows the before-and-after patch — use it to audit an edit, and note that it is the only view that shows anything the change removed. Document shows the proposed spec as it will actually read once published, with the lines the change touched highlighted. Reach for Document when the question is “is this the right spec?” and Changes when it is “what exactly did they alter?”.

Where to go next

API keys	Publishable vs secret keys — which one you need, and how to keep them safe
Bug reporting API	Catch runtime errors on your site and collect user feedback
Contacts API	Add contacts to your CRM from your own backend
Errors and limits	The error shape, rate limits, and retry behavior both APIs share
CLI	Run your company from the terminal
Connectors	GitHub, Vercel, Netlify, Cloudflare, Slack