Personas, secrets & agents

Workflows lean on three shared building blocks: personas to sign in, secrets for sensitive values, and agents — the machine that actually opens the browser. The idea across all three: sign in once, act on your own accounts, and never write a credential into a workflow.

Writ runs on your own accounts, with your own credentials and data, on sites you are authorized to use.

personas ▸ one login, many runs

Personas

A persona is a reusable, encrypted identity for one site: you sign in once, and every workflow or monitor that targets that site reuses it — each target references its own persona_id. Credentials come from the vault; a persona can also carry a second factor.

TOTP

Paste the authenticator secret once. Codes default to 6 digits on a 30 s period, are minted at the moment the 2FA step runs — on-device when the run is local — and are never written to logs.

On cloud runs, automatic 2FA minting is a premium capability (Pro and up) — below that, the run answers 402 premium_feature_required. On your own local agent it works on every plan.

Email & SMS codes

For sites that send one-time codes instead, the workflow reads the code from a mailbox you connect under integrations. This read path is cloud-only: a local run that reaches such a step finalizes as twofa_required instead of guessing — see Where it runs.

secrets ▸ the vault

Secrets vault

Store sensitive values once and reference them as {{vault:key}} in any workflow field, so plaintext never appears in a recipe. Subfields pick one part of a stored item — {{vault:name.username}} — and the bare reference has a deliberate default: for a credentials item it resolves to the password, for a card item to the card number. Values resolve only at run time, on the agent executing the run.

The API returns names and metadata only, never values: a credentials secret exposes only its username, a card secret only its last four digits. Card numbers and CVCs are never cached and never returned.

Two channels, two syntaxes

They look similar and are not interchangeable:

Channel	Reference	Resolved
You, in workflow fields	`{{vault:key}}`	At run time, on the executing agent.
The AI channel	sees `[SECURE:key]`, emits `{{secret:key}}`	Only at dispatch — the model never sees the value.

Lock & unlock

The vault can be locked. While it is, any run that needs a secret fails with 423 vault_locked — nothing falls back to a cached value.

agents ▸ which machine

Agents

An agent is the machine that opens the browser. You choose it per workflow:

	Local / BYO agent	Writ Cloud
Compute charge	None — never gated, metered or charged	Metered from the plan’s monthly pool, then the wallet
Runs on	Your own machine	The managed fleet
Intranet-only systems	Reachable	Not reachable
AI / provider keys	Stay on your machine	Managed (unless BYO-AI)

There is a third venue too — running the open-source coordinator on your own infrastructure. The full comparison, including what is cloud-only, lives on Where it runs.

alerts ▸ six channels

Notifications

Alerts from monitors, runs and automations reach you over six channels — in_app, email, sms, whatsapp, signal, pushover — tuned per category in your preferences. The grid and its locked always-on cells are documented under Users & teams.

connections ▸ oauth

Integrations

Integrations are OAuth connections Writ uses on your behalf — a connected mailbox is what powers email-code 2FA above. Connections are scoped to what they are for, and revocable at any time.

What next

Workflows: reference personas and secrets in a run.
Where it runs: local, cloud and self-hosted, side by side.
Monitors: alert on change through these channels.