Run your go-to-market on GTM OS

Prefer to do it by hand?

Goal: install an instance and connect an agent workspace without /setup-gtmos. Commands are bash; on PowerShell use $env:NAME = "value" instead of export.

1. Install the instance into its own folder (owner plus approver; passwords are generated into its .env):

   gtm setup gtm-instance --org "Acme" --email you@acme.com --approver-email cofounder@acme.com

   Port busy? Add --console-port, --api-port, --mcp-port or --postgres-port. Local images only? Add --version <tag> --no-pull. The ports bind to 127.0.0.1 unless you add --bind <address> (see Self-host on a server).
2. Sign in as the owner (it prompts for the password, or reads GTMOS_PASSWORD). Your org id is ORGANIZATION_ID in gtm-instance/.env.

   export GTMOS_API_URL=http://127.0.0.1:3001 GTMOS_ORG=<org id>
   gtm login --email you@acme.com --console-url http://localhost:3000

   Run the export GTMOS_TOKEN=... line it prints.
3. Create the agent key (shown once):

   gtm token create --name claude-code --client claude-code --preset full-gtm-engineer --expires-days 90

4. Put the key in GTMOS_AGENT_TOKEN (per OS), then connect your workspace folder and check:

   gtm init --url http://127.0.0.1:3001 --key <agent key> --yes
   gtm doctor

5. Start claude in the workspace and run /mcp.

Accounts and team

Goal: the right people with the right roles, including a second approver.

There is no read-only viewer role. Role profiles live in Settings > Members (a Profile column and a Role profiles editor). In the setup wizard, saving the operator, ops lead and exec seats assigns the matching profile. Changes to your own profile may only narrow you; widening needs another owner or admin.

1. Settings > Members, Invite a member: email, role (member, admin or owner), Invite. Pending invitations are listed below.
2. Or provision a verified teammate from a terminal (run it yourself, so your agent never sees the password):

   gtm member add --email approver@acme.com --password '<password>' --role admin --org <org id>

3. Stop an agent everywhere: Settings > Agents, Kill. Revive it there later.
4. Agencies: Settings > Delegations lists access granted to an agency org; revoke it there.

Invitations are sent by email. If your instance has no email transport yet, set one up first (Email for invitations, password reset and nudges), or use gtm member add above, which needs no email.

Email for invitations, password reset and nudges Needs a human

Goal: your own instance can send its system mail: team invitations, password reset, email verification and setup reminders. This is a different thing from the sending lane you use for outreach (see Email sending).

GTM OS does not ship with a mail provider. You choose one for your instance in .env. SMTP works with almost any provider, so it is the usual choice.

1. Set the variables in .env, for example:

   EMAIL_TRANSPORT=smtp
   SMTP_HOST=smtp.example.com
   SMTP_PORT=587
   SMTP_USER=postmaster@example.com
   SMTP_PASS=<password>
   EMAIL_FROM=GTM OS <no-reply@example.com>

2. Run gtm up again so the containers are recreated with the new values (changes to .env apply only then).
3. Check it: gtm doctor lists the email transport, then invite a teammate in Settings > Members and confirm the mail arrives.

What breaks without it

• Invitations (Settings > Members > Invite) and email verification need a transport. A person who signs up and is never sent a verification mail cannot accept an invitation meant for them.
• Password reset mail is not sent, so people who forget a password cannot reset it themselves.
• Setup reminder emails to your own team (operator nudges) are not sent. The reminder still appears in the console, and the nudge says email is not configured.
• The instance still starts and the first owner can be created, because a missing mailer never blocks setup. Each skipped mail writes a warning with the recipient and the kind of mail to the API log. The link itself is never logged by the release images, because a reset or verification link is a secret. Only a local development run outside production prints the link to the terminal.
• A mail server that is configured but broken is an error you will see, unlike a missing one.

Without email, today

Add a teammate with gtm member add (see Accounts and team). It creates a verified account without sending anything.

Connect your tools

Goal: every engine you use has what it needs. Where things live:

Keys are sealed on save and never shown again. Connecting needs an owner or admin, or their agent (the Full GTM engineer key can store keys you give it). Sign-in buttons (OAuth) always need a person to click.

The Connections page

• A grid of logo tiles in 11 categories (CRM, email and outbound, ads, analytics, search and SEO, conversations and calls, enrichment and data, models, messaging, warehouse and billing, other and MCP). Each tile says whether it connects Native or Via Composio and lets you choose.
• Search the grid (press / to jump to the search box) and sort by relevance to your setup (the default), A to Z or connected first.
• A Needed strip at the top lists what your chosen blueprint and the engines you picked still need. Statuses are honest: live, stored but not verified, failed, or not connected. In demo mode a tile says it uses built-in sample responses, not your data.
• Connectors with no native card yet (Instantly, lemlist, Smartlead, Gong, Mixpanel, Amplitude) connect through Composio.

Composio: connect your own apps Needs a human

Goal: GTM OS can read and act in your CRM and other SaaS apps. Composio is never used to buy data.

1. Integrations > Connections, Composio card, click Connect Composio (recommended: OAuth sign-in, tokens refresh on their own).
2. Prefer a key? Click Advanced: paste a Connect key ck_... (connect.composio.dev) or a project key ak_... (platform.composio.dev, project, Settings, API Keys). The key is verified live before it is saved. One Composio credential per org; the last one saved wins.
3. Click Sync connected apps: apps already connected in your Composio account become ACTIVE; apps no longer connected become inactive.
4. A new app: search the App catalog, click Connect, finish the hosted sign-in (the link lasts about 10 minutes).
5. Several accounts for one app? Next to the app click Use an existing connection, then Use this on the right one.
6. CRM of record section: pick HubSpot, Salesforce, Pipedrive, Attio or Zoho, then Sync now. It also syncs every 6 hours.
7. Any other app: on the connected app click Map to ontology (see Bring data in).

API keys: model, looot, email

Goal: a model provider and looot are live (and Resend if you send through it).

1. Integrations > Connections, Add a connection.
2. Provider: anthropic, gemini, openai or openrouter (at least one of these four), looot, resend. Give it a label, paste the key, add it.
3. Run Test on the new connection. A stored but untested key reads "Stored, not verified".

OpenRouter is a model router: one key reaches the models of many vendors (named <vendor>/<model>), and it is used for text generation only. Semantic search needs an OpenAI or Gemini key (Anthropic and OpenRouter have no embedding model here). Without one, search is full-text only.

Google and Microsoft accounts Needs a human

Goal: mail and calendar sync, sending from your mailbox, and Search Console, GA4 and Google Ads data.

1. Settings > Connected accounts.
2. Choose Google or Microsoft, tick the features (Read mail, Send mail, Calendar; Google also Search Console, Google Ads), connect and accept the consent screen.
3. For Search Console, GA4 and Google Ads, click Use for org on the Google account. Those read through the org default account.
4. Ask your agent to set the Search Console property, or give it: sc-domain:acme.com or https://www.acme.com/.

Slack Needs a human

Goal: alerts and approvals reach your team in Slack.

1. Settings > Slack, connect the workspace and accept the consent.
2. Channels: search, join, or Create a channel with the GTM OS bot in it.
3. People matching: Match by email links members to Slack users; fix the rest with Set match.

For alerts, the native Slack connection is preferred over Composio's Slack toolkit.

Microsoft Teams. Teams appears in Integrations > Connections as a chat tile for alerts and approvals, and it connects through Composio. It has no settings page of its own like Settings > Slack, so there is no channel or member matching screen for it. CRM > Conversations lists Teams as one of the reply channels.

Email sending: domain, lane, mailbox

Goal: real emails can go out, only through an approved lane and a bound mailbox.

1. Sender. Best: a Gmail or Microsoft 365 account with Send mail in Settings > Connected accounts. Otherwise a resend connection (verify your domain in Resend first).
2. DNS Needs a human: at your DNS host add SPF (one TXT starting v=spf1), DKIM (the record your provider shows at <selector>._domainkey.<domain>) and DMARC (TXT at _dmarc.<domain>, for example v=DMARC1; p=none; rua=mailto:dmarc@<domain>). Check:

   nslookup -type=TXT acme.com
   nslookup -type=TXT _dmarc.acme.com

3. Lane. Your agent writes the lane (definition.lane: daily cap, sending domain, sender postal address, budget). Sign and promote it (Environments).
4. Activate the lane. Engines > Outreach, open the Outreach workbench link, Sending lanes, click Activate lane (optional DKIM selector). Or:

   gtm lane activate <laneKey> --env prod

   A different person approves and executes it in Approvals.
5. Mailbox. Bind it when you send: pick it in Sending mailbox on the workbench or on a new sequence.

LinkedIn through Unipile Needs a human

Goal: read LinkedIn profiles, inbox and connections, and send LinkedIn steps through the same approval path as email.

1. Integrations > Connections, Unipile (LinkedIn sending) card.
2. Fill API key, DSN (your account's API host, for example api8.unipile.com:13814) and optionally the LinkedIn account id.
3. Click Save and test.
4. Needs a human Accept the LinkedIn risk, once. LinkedIn may restrict or ban accounts that send automated messages, so LinkedIn sending is off until an owner or admin accepts that. Open Outreach, the Sending lanes panel, and click Accept the LinkedIn risk. It is recorded in the audit log, and there is one acceptance for connection requests and one for messages (the button accepts whichever is still missing). A person does it, never an agent. Until then every LinkedIn send is refused, and the panel says so.
5. The same panel shows the Unipile webhook address and the header it expects. Point Unipile at it so acceptances and replies arrive at once (an hourly check is the backstop). The secret comes from UNIPILE_WEBHOOK_SECRET on the instance, and owners can reveal it there.

Add your own MCP server

Goal: an internal tool becomes a data source or capability for GTM OS (the opposite direction from your agent's MCP).

1. Integrations > Connections, MCP servers card, Add an MCP server: server name (lowercase), server URL (a streamable-HTTP endpoint, usually ending /mcp), optional auth header name and value. Credentials go in the header, never in the URL.
2. Test it: the tool catalog loads.
3. Needs a human Mark each tool Read or Write (approval). An unmarked tool cannot be used.
4. Ask your agent to bind a capability to it, or map its records (see example prompt).

Required connections and readiness

Goal: know what is live and what is missing.

1. Top of Integrations > Connections: Required connections. States: Connected, Stored not verified, Failed, Required: missing, Not connected, Not needed.
2. From a terminal:

   gtm doctor --strict

Connect Claude Code, Codex or any MCP agent

Goal: your agent talks to GTM OS through MCP with its own key, acting for you.

1. Settings > Developer, Connect Claude Code / Codex: choose the Coding agent (Claude Code, Codex or Other MCP client), an Agent name, Preset: Full GTM engineer, then Create agent key. Copy the key now: it is shown once. The page also shows the org id, the MCP endpoint and setup snippets.
2. Or from a terminal with your owner session (gtm login first):

   gtm token create --name claude-code --client claude-code --preset full-gtm-engineer --expires-days 90

3. Put the key in your environment, never in a file.

   Windows PowerShell (persistent; then open a new terminal):

   [Environment]::SetEnvironmentVariable('GTMOS_AGENT_TOKEN', '<agent key>', 'User')

   macOS / Linux: add this line to ~/.zshrc or ~/.bashrc, then open a new terminal:

   export GTMOS_AGENT_TOKEN='<agent key>'

4. In your workspace folder, connect it to the instance (writes .mcp.json with Bearer ${GTMOS_AGENT_TOKEN}, AGENTS.md for Codex, .claude/ and docs/gtmos/):

   gtm init --url http://127.0.0.1:3001 --key <agent key> --yes

5. Restart the agent in that folder. In Claude Code run /mcp.
6. Later, pull fresh docs, skills and subagents from your live org (files you edited are kept):

   gtm init --refresh --yes

Codex and other clients default to record.read, record.write, engine.configure. Choose the Full GTM engineer preset if they should manage connections too.

Skills, subagents and agents

Goal: know what your coding agent arrives with, and how GTM OS runs agents of its own.

The 16 organization agents

They read, draft and propose. Every send, CRM write, merge and publish they propose is approved by a different person, the claims gate checks the content, and Dry Mode ends at the draft. They cite the records behind what they say. They never run a paid enrichment themselves: it quotes the cost and hands it to a person. Turning a pack on or off is a request a second admin approves, in Settings > Agents under Agent packs. Enable stdlib/pack.core-skills before the core agents, because they use its skills. Pack agents that start on a trigger keep the storm guards: no bulk sources and the default fire cap.

1. After you upgrade the CLI, take the newest skills and subagents in each project folder:

   gtm init --refresh

   Skills and agent files you edited are kept.
2. Ask for a role by name, for example "gtm-operator, brief me on today" or "deal-reviewer, review the deals closing this month".
3. Watch or stop agents in Settings > Agents (kill, revive). An evaluation pass by eval-reviewer shows what organization agents did before you widen their autonomy.

Your agent reaches GTM OS over MCP with eight meta-tools: gtm_describe (always first, it lists every operation), gtm_query, gtm_get, gtm_search, gtm_act, gtm_approvals, gtm_lineage (the audit trail behind one approved or executed action: who proposed it, who approved it, what ran) and gtm_lineage_trace (the receipts behind a record's values: the surviving value, the rule that chose it, the sources). Everything the console does is an operation, so console and MCP stay in step. The agent proposes. A person approves.

Setup wizard Needs a human

Goal: turn what your company already knows (answers, website, connected data, documents) into the definitions your engines run on. Nine steps on six screens. Open Setup in the console. Your agent can run the same steps over MCP (say "set up GTM OS for my company") and you can take turns: what one saves, the other sees.

Rules that hold on every screen

• No invented values. Every suggestion shows the facts it rests on: an answer you gave, a page of your site, a document, a real count from a connected source. A value nobody knows yet stays empty and becomes a numbered open ask with an owner. With no model configured the page says so and fills only what the data supports.
• Every saved answer changes engine behavior. A card is published through the operation that owns that definition, with the same permissions, approvals and audit as anywhere else.
• The proposer never approves. Change sets, journeys, blueprints and promotions are approved by a different person in Approvals. Definitions are signed by someone other than the proposer.

Good to know

• Documents: PDF with text, Word, Excel, CSV, JSON, Markdown and text, up to 10 MB each and 50 per organization. Scanned PDFs and images are refused with the reason. Suppression lists, a DPA and any file with emails or phone numbers are restricted: only owners and admins read their text, and they are never sent to a model.
• The ARR band is private: only a human owner or admin sets or reads it, and it is hidden from agents.
• Cards approved on screens 3 and 4 land in dev. Launch is human only: it signs and promotes the setup definitions and turns an engine live only where its autonomy card says so.
• Seats narrow what a role may do and never widen it. Never put the sole owner in the Operator or Exec seat. GTM OS refuses any change that would remove the last person who can still run the build, approve cards and launch.
• If the wizard says someone else changed the session, re-read it and redo the step.

Build your GTM system with your agent

Goal: a full, customized setup from one conversation.

1. Run /build-gtm-system (optionally with a goal, for example /build-gtm-system B2B SaaS sales-led, outbound + SEO).
2. Answer the discovery interview, asked in batches: business and offer, ICP and tiers, personas, markets and compliance, channels, CRM and tools, data volumes, team and approver.
3. Claude reads the live state, recommends the closest general blueprint with a reason, and applies it in dev.
4. Engine by engine (data first, then Score, routing and plays, then Outreach, SEO & GEO, Ads), it explains, shows defaults, asks only what matters, writes the definitions, and verifies live.
5. You approve proposals (approver window), then go live with sign and promote.

Blueprints you can start from: b2b-saas-sales-led, enterprise-abm, b2b-saas-plg, devtools, agency-services, b2b-marketplace, dtc-b2c, and the starters outbound, seo, full-gtm (the last two require Search Console). Browse them in CRM > Blueprints, View & apply.

Blueprints: what each one sets up

Goal: pick the closest general template, know what it creates and which connections it makes required. A blueprint seeds a whole motion (personas, segments, scoring, suppression, bindings, lanes, plays, metrics) in one change set. They are general templates: start from the closest and customize, never one per customer.

In the table, "model provider" means Anthropic, OpenAI, Gemini or OpenRouter. "Email sender" means Gmail, Microsoft or Resend. "CRM" means HubSpot, Salesforce or Composio. Applying a blueprint makes its declared connections required in readiness, and optional ones are listed without being required. Browse and apply them in CRM > Blueprints.

Blueprints on the command line

To start from a blueprint, gtm plan --from <id> previews it and gtm apply --from <id> --env dev proposes it. A different person approves, then you sign and promote the definitions (see Environments and going live). A search blueprint needs --gsc-property on a live instance.

First wins and operator nudges

Goal: always know the next useful step, based on what really happened in your workspace.

1. Open Home or Setup. The first-win card lists eight milestones: the instance is ready, a real data source is connected (not a fixture), the first sync finished, a person signed the first definition, the first Dry Mode draft was produced, accounts have fit scores, a second person approved a proposed action, and the first live message went out.
2. Each open milestone says what to do next. A fact GTM OS cannot read reads "unknown", never a guess.
3. Ask your agent "what is my next first-win step?" for the same answer.

Operator nudges

• Owners and admins get an in-app nudge when something needs them.
• Email is opt-in. Each person turns it on in their own notification preferences. Every email carries a signed unsubscribe link that works without signing in, and nobody gets more than one a week.
• If email is not configured on the instance, the nudge says so plainly instead of pretending it was sent. gtm doctor shows the email transport as an optional line.
• An owner or admin can invalidate every earlier unsubscribe link (notification.preferences.revoke_links, a human-only operation).

Does your harness match?

gtm init records which CLI, which skills release and which operation list it generated your project files from. gtm doctor compares that with what is running and reports a stale harness with the fix: gtm init --refresh. A project created before 0.2.5 reads "unstamped", which is informational.

Customize engines

For engine-by-engine knobs, prompts and checks, see Engine by engine in the engineer guide.

Goal: the engines follow your rules, not the defaults. Ask your agent in plain words; it edits the definition in dev, and you sign and promote it.

Simulate a play before it runs (zero writes):

gtm play simulate <playKey> --env dev --since 30d

Customize the data model

Goal: track the fields and objects your business needs.

Custom fields (companies, contacts, deals)

1. Settings > Custom fields, pick Companies, Contacts or Deals.
2. Create a field: label, type (text, long text, number, date, checkbox, select, url, email, phone, user), options for a select, then Required, Show on record, Show in tables, Allow filtering (select and user fields only) and Allow agent fill (with instructions) as needed.
3. Create field. It takes effect at once, no approval, and appears on the record page.
4. Know what the two list flags do today: Show in tables and Allow filtering are saved, but the Companies and Contacts lists do not read them yet. Columns and filters for custom fields arrive in a later release. Meanwhile the field works in records.list filters and for your agent.

Custom objects

1. Check first whether a module already has it (for partners: stdlib/gtm.partner in Settings > Packages).
2. CRM > Model, Define a custom object: label, description, fields. Validate.
3. Needs a human Publish; a different person approves it in Approvals.

Bring data in

Goal: your accounts, contacts and deals in GTM OS, clean and de-duplicated.

From your CRM

1. Connect the CRM on the Composio card, pick it under CRM of record, click Sync now.

From any other app

1. On the connected app in the Composio card, click Map to ontology.
2. Pick a list tool, preview live sample data, map fields to a target (company, contact, deal, signal or a custom object).
3. Propose it; a person signs it (and promotes it if prod should run it); then Sync now.

From a CSV

1. CRM > Import, What are you importing?: companies, contacts or deals.
2. Choose the CSV file (or paste it). The first row is read as headers.
3. Map your columns, then Preview: every row shows Create, Update or an error. For contacts, a company column links each contact to an account: GTM OS matches by website first, then by name.
4. Commit (owner or admin by default; see Security defaults). Large files run in chunks, and files that link contacts to companies run in chunks of 200 rows.

From looot (lists and enrichment)

Ask your agent, for example "find 50 logistics companies in Germany with 200 to 2,000 staff". It prices the request first and asks before more than about 100 paid calls. Each call is capped (default $0.05); above the cap it waits for an approval.

After every import

Run the data-quality pass in CRM > Data quality, or ask your agent to normalize, backfill domains, scan duplicates and propose merges.

Use each engine day to day

Goal: know which button does what.

Hot list and signals

1. CRM > Hot list: accounts ranked by score, latest signal, verdict, owner. Filter by verdict, signal, owner, activity; sort by score, latest signal or name.
2. Click Why this score on a row for the reasons.
3. Scan for signals now runs the daily looot signal scan on demand (owner or admin; capped per run, never above $1). The button is disabled, and nothing is queued, while the organization-wide Dry Mode is on, because a scan spends real looot credits. It is also disabled while the scan is switched off in Settings > Feature flags (signals.scan). The page says which of the two applies.
4. CRM > Signals is the feed of signals with their evidence. A review queue lets you verify or dispute them. With the verification gate on Strict (the default for new workspaces) an unverified third-party signal never scores and never reaches a seller. Signals from your own systems (first party) are verified by default, so a first test that only uses a scan or looot data can show an empty Hot list until you verify some signals in the review queue. Workspaces that existed before the gate run it Off until an owner or admin sets it (owners and admins choose Off, Hide from sellers or Strict on the Signals page, and every account is rescored when the choice changes which signals count).

Companies, contacts, deals

• CRM > Companies / Contacts: search, filter, create, bulk actions. A company page has tabs: Overview (firmographics, score, signals, custom fields), Contacts, Deals, Tasks, Activity, Research, Evidence, Agent.
• CRM > Deals: pipeline board and table. Edit pipelines and stages in Settings > Pipelines.
• CRM > Tasks: due today, overdue, done.
• The Evidence tab shows where each value came from. A value you edit by hand is never overwritten by automation.

Enrichment

1. CRM > Companies, select rows, choose Enrich in the bulk actions.
2. Read the cost preview, confirm.

• Engines > Enrichment shows the mode, fill rate, spend, bindings, freshness windows, newer enriched values and runs.
• Every value written carries when it was verified, a freshness window and a confidence. Stale values that enrichment owns are re-checked on a schedule. A value you edited by hand is never touched.
• A newer enriched value replaces the one on a record only through an approval, with undo.
• A monthly spend cap applies, and when money is limited the best accounts are enriched first.
• If a provider is down (unavailable, a timeout or a server error), enrichment moves on to the next provider in the binding instead of stopping. Lookups run with your workspace key; the instance key is only a fallback.

Score

1. Engines > Score: To score, Accounts, Rescan. Click Qualify on an account.
2. Open the account for its qualifications, or the company page for Why this score.
3. Reps flag a score they disagree with from the lead queue (Flag this score).
4. The Learning section shows the last run, proposed changes with their evidence and lift, calibration and rep disagreement. Scoring records each verdict, measures what happened afterwards (a positive reply, a meeting, an opportunity, a won deal), and proposes a new scoring model version. Needs a human A person other than the proposer approves it.

The first rescan after upgrading to 0.2.5 re-scores accounts once and scores can move. Ask your agent for a rescan preview first (score.rescan_preview). The upgrade rescore never hands off, routes or enrolls anyone.

Outreach

1. Engines > Outreach lists pending sends. Click the Outreach workbench link (top right).
2. Pick a contact, Draft message, edit subject and body.
3. Pick the Sending lane and the Sending mailbox (Choose a mailbox…), then Propose send.
4. Needs a human A different person approves and executes it in Approvals.
5. Cadences: CRM > Sequences, New sequence (name, goal, sending lane, sending mailbox). Edit its Steps: ordered steps, waits in days or business days counted in the recipient's timezone, send windows, templates or briefs, weighted A/B variants, and exits on reply, unsubscribe, bounce, a booked meeting or a stage change. Enrol people from a company page with Enroll people in sequence. Members, Messages and Replies tabs track it.
6. Signal plays (funding, hiring, intent) enrol one person per signal into an approved sequence, with a daily cap. Personalization is tiered (1:1, 1:few, 1:many) and grounded in your proof library.
7. Reply next steps are proposals, never automatic. Gmail and Outlook delivery-failure reports are applied as hard or soft bounces and never read as replies. Undoing a bounce (outreach.bounce_undo) is human only.
8. What's working on the Outreach page shows reply and meeting rates per group once a group has at least 30 sends.

Merges, identity and data quality

1. Engines > Merges (and CRM > Data quality): quality score, field fill rate, Duplicate candidates, merges waiting for approval, recent merges with undo.
2. The duplicate scan follows your signed identity rule. Choose the survivor, Merge. Conflicts are decided per field by a strategy and listed on the approval. The merge is a proposal; once executed it can be reversed with Unmerge, and fields you set by hand on the survivor are kept.
3. Uncertain identity matches wait in Operate > Needs a human.

SEO & GEO Search Console required

1. Engines > SEO & GEO: readiness metrics and pages. Click the Page workbench link.
2. Track a new page, Track page, then Audit page, Get recommendation, Propose change (a person approves).
3. Site visibility: Run visibility for Search Console totals, top queries and pages (and Ahrefs metrics when Ahrefs is connected through Composio).
4. Plan content with topic clusters, briefs and drafts. A draft passes a quality gate and moves through lifecycle states. Pages needing a refresh are listed with the reason.
5. Needs a human Publish an approved draft to your CMS: Webflow through Composio, WordPress.com as drafts only, or a signed webhook (also the route for self-hosted WordPress). The body published is the approved draft, bound to its hash.

Set up SEO publishing

The SEO & GEO engine page has tabs: Overview, Visibility (Search Console totals, top queries and pages), GEO (AI-answer visibility), Keywords (opportunities), Clusters (topic clusters), Factory (briefs and drafts), Fix queue (audit findings to fix), Publish queue, Refresh calendar (pages due a refresh), Settings (the tracked-visibility schedule, alert thresholds and the spend cap per run; turning it on needs a live Search Console) and Pages.

1. Needs a human Connect where pages go. For Webflow or WordPress.com, connect it in Integrations > Connections > Composio with your own credentials. For your own site, including self-hosted WordPress, register a publish endpoint with a URL and a signing secret (webhooks.create) and put a small receiver on your site. Composio has no toolkit for self-hosted WordPress.
2. Open an approved item in Factory, then its Publish tab, then CMS targets > Settings. Set the default target and the Site URL (without it a new page's live address is unknown). For Webflow add the collection id the pages live in. For WordPress.com add the site id. For the webhook add the endpoint id.
3. Webflow reads three fields from each draft: title into name, address into slug and body into post-body. If your collection uses other field names, set the field map (webflow_field_map under the cms provider settings, with keys title, slug and body; your agent can set it, there is no form field for it).
4. Choose the CMS target (each shows Ready, Needs setup or Not connected), check the preview of exactly what will be sent, and click Propose publish. A different person approves it in Approvals. The page then moves from Approved to Published once the CMS confirms.

• WordPress.com stages drafts only. The toolkit never publishes, so the page is never called published.
• The body is read from the approved draft and bound to its hash. Editing the draft voids the approval, and the claims gate and brand safety run again when the publish executes. A retry never creates a second page.
• Undo: Propose take-down on the same tab. A different person approves it.
• Refresh: the Refresh calendar lists pages that decayed, with the reason: clicks down (20% by default), ranking down (3 places), a lost AI citation, or age (180 days by default). The two thresholds are organization settings (refresh_traffic_drop_pct and refresh_age_days under cms). A refresh is a revised draft through the same flow.

Performance Ads

1. Connect Google Ads (connected Google account with Google Ads) or a meta_ads connection.
2. Engines > Performance Ads, then the Campaign workbench link: pacing and performance per campaign.
3. Propose a change: new budget (increases capped at 2x) or status, Propose change. A person approves: this is real money.
4. Set a target in definition.unit_economics (ask your agent) and the engine paces toward it. A nightly allocator proposes budget moves. It never executes them. With no target set, behavior is as before.

Routing

1. Engines > Routing: territories (criteria, stickiness, overflow), manual assignment and the assignment history with the reason for each decision.
2. Team capacity: caps per type, weights and out-of-office per person. A full owner's records are spread over the eligible pool.
3. Lead-to-account matching attaches a lead on its own only on an exact domain match. Use the match preview to see who a lead would route to.

Plays

1. Engines > Plays: every play, its trigger, a dry run, manual fire and runs. The Results tab shows runs, actions, outcomes, credited revenue and spend per play.
2. Nine plays ship in the blueprints: speed to lead, meeting prep, meeting follow-up, stage-stuck nudge, closed-lost win-back, renewal runway, champion change, content refresh and enrich on create.

Attribution

1. Settings > Money > Attribution: choose position-based or a per-channel model next to the equal split. Until you choose, your numbers stay on the equal split.

Research agent

• CRM > Research: what it researches now, scheduled re-checks, failures to retry or cancel.
• Settings there: Workspace profile (enter your website, Refresh), Research enabled, Auto-apply verified facts, Daily budget (USD), re-check days, meeting-prep lead time.
• Per company: the Research tab.

Search index

1. Settings > Search index: records indexed and with vectors per type, the embedding model. Reindex now (owner or admin).

Agent tab and AI chat

• Open a company, contact or deal, Agent tab: ask about that record.
• CRM > AI chat: ask about the workspace. Its changes (log activity, tasks, edits, stage moves, enrolments) are only proposed. Needs a model provider.

Watch the system

• Mission Control: today's move, KPIs, risks, the overnight engine log.
• Operate: Needs a human, Runs (step-by-step traces), Monitors, Cost (every cost line back to the run that spent it).
• Settings > Navigation: hide whole tab groups you do not use.

Run the system day to day

Goal: know which page answers which daily question: what happened, what waits on me, what was sent and can it be pulled back, what to build next, what customers said, and whether the data is whole.

Daily update Operate > Daily update

A fixed report card with four numbered sections: Done yesterday (what each engine executed and how many have an outcome, approvals given, asks closed), Waiting on a human (approvals pending, items held by a guardrail, signals to review), Open questions (the numbered asks with owner, due date and an Overdue mark) and Sync health (the last result per source sync). It covers the day before. The history on the right opens any earlier card.

1. Get it yourself. In Send it to me, switch Daily update on and choose the channels: In-app, Email, Slack DM. Nobody receives it until they opt in, and you see only what you are allowed to see.
2. Needs a human Schedule it for the team (owner or admin). In Schedule: Generate every day, the local hour (0 to 23), the time zone, and an optional team Slack channel id. The default is 08:00 UTC, with no AI summary.
3. Optionally switch on Add an AI summary. It is written from the card by your model, it needs a live model route, and it is always labelled "AI summary (written by <model> from the card; check before acting)". It is written from organization-wide records only, so private and team records never appear in it. If it cannot be produced, the card says why instead of inventing one.
4. Generate now rebuilds today's card from live data, replaces the stored one and delivers it to everyone who opted in.

Email and Slack delivery use the organization's own Resend connection and Slack connection (matched members only). Without them the delivery reports not configured, and in-app always works. This is separate from the instance mail described in Email for invitations, password reset and nudges.

Open asks Operate > Open asks

The numbered ledger of every question the system is waiting on a person to answer. Each ask is numbered (#1, #2, and so on), has an owner, a due date, a priority (Low, Normal, High, Urgent) and a status (Open, Answered, Resolved, Dropped). New asks come from you, from the setup wizard (a missing access grant becomes an ask), from Studio, from stage-mapping reviews and from data completeness flags. Kinds you can create are Question, Document request, Access request, Approval needed and Data gap.

1. Read the strip at the top, including Waiting on you: open asks you own, directly or through your role.
2. Filter by status, kind, priority or overdue, tick Waiting on me, or search by words or by number (for example #12). The list shows the exact total and a Load more button.
3. Click an ask to open it. You can answer, resolve, drop, reassign or Remind now.
4. New ask: choose the kind and priority, write one clear question and the context, choose an owner (a person or a role) and a due date.
5. Owners and admins: open the chasing settings. Send reminders, remind every N days (1 to 30), the local hour, the time zone, the default due date (1 to 90 days), how many days overdue before it escalates (0 to 30), the escalation contact (the owners and admins by default), and the channels In-app, Email and Slack DM.

The Waiting on you badge in the header counts the open asks you own plus, if you are an approver, the approvals waiting for your decision. It is hidden at zero, refreshes about every minute, and opens Open asks filtered to you. Agents see open asks in their context and do not ask the same thing twice. Reminders go by email through the organization's Resend connection, and by Slack when the member is matched in Settings > Slack. People outside your team are reminded by email only.

Actions Operate > Actions

The ledger of everything the engines drafted or did: a draft, a send, a budget change, a page publish, a CRM write, a merge, a task, a meeting. Each row shows the engine, its status (Drafted, Pending approval, Approved, Executed, Failed, Undone, Rejected, Cancelled), the gate it went through, the outcome it produced and its undo.

1. Pick a window (7, 30 or 90 days) on the strip at the top. It counts drafted, approved, executed and with an outcome, per engine, with a conversion rate.
2. On the Actions tab, filter by engine, status, gate, type or outcome, or search. Click a row for the approval, the audit trail, its batch and its undo plan.
3. Undo one action from its detail. A sent message cannot be un-sent, so for a message the undo records a retraction note. An undo that changes the outside world is proposed for approval, and the row shows Undo pending until it is decided.
4. On the Batches tab, each send batch (a cadence rescan, a batch send) shows its counts. Pull back cancels every draft and every send not yet out, withdraws proposals waiting for approval (or rejects them if an owner or admin does it), revokes approved ones, and leaves anything executing right now alone. The box Also undo what already executed is ticked by default. Add a reason if you want one kept on the record. View actions opens the Actions tab filtered to that batch.

Studio CRM > Studio

Ask for a new play or app in a sentence. The system drafts the spec, every open question becomes a numbered ask, and it ships once a second person approves. The page has three tabs: Plays (the play catalog scored on impact and ease for your organization, sortable and filterable, each score explained), Requests (the board: ask, spec, numbered asks, approval, shipped) and Scoring (the weights behind the scores; owners and admins change them). Click Ask for a play, describe what you wish existed, and follow the request across the board.

Conversations CRM > Conversations

Conversation memory, in four tabs. Replies: every reply with its label (interested, not now, objection, referral, unsubscribe, out of office, bounce and the labels you define) and what the label triggered; you can relabel a reply, re-run it, or link it to a record. Calls: transcripts; add one, sync from Fireflies, edit, archive. Coverage: how much conversation GTM OS holds per source. Labels: your reply labels, the words and senders that recognise each, and the effect of each (stop a sequence, suppress an address, raise a signal, open an ask, create a follow-up task).

Data health CRM > Data health

How much of each connected source GTM OS actually holds. Per source (your CRM of record and each signed source mapping) you see its state, its connection and its last and last full sync. Per object you see the source count (and how it was counted), what is mirrored, what is held on unmapped stages, a completeness bar against the threshold, a flag when it falls below, and the latest parity check against the live source. Click an object for the field-by-field differences (money to the cent) and its audit history.

1. Owners and admins: Run audit, Check parity and Sync now.
2. Audit settings: the flag threshold (1 to 100 percent), the parity sample size, auto backfill (it never runs while the organization or the CRM write-back engine is in Dry Mode) and the nightly audit.

Approvals Needs a human

Goal: nothing customer-facing or live happens without a second person.

1. Approvals (top of the sidebar) or Operate > Needs a human. Open a proposal: The change shows exactly what will run.
2. Approver: Approve or Reject. Then Execute runs it.
3. Veto your agent's proposal: as the person the agent acts for, open it and click Withdraw (veto my agent's proposal).
4. Pause everything customer-facing: Settings > Safety, Enable dry mode. Effects become drafts; a banner shows on every page. More in Dry Mode and guardrails.

Dry Mode and guardrails

Goal: see what would have happened before anything real goes out, and keep going live a deliberate choice, one engine at a time.

1. Organization-wide. Settings > Safety, Enable dry mode. Customer-facing actions become drafts: logged, never executed, no approval created. A banner shows on every page. Turning it on or off is human only (owner, admin or builder).
2. Per engine. In Settings > Safety (the Engines card) and in the header of each engine page, every engine has its own Dry or Live mode: outreach and sequences, meeting booking, performance ads, SEO & GEO publishing, lifecycle plays, routing notifications, CRM write-back, enrichment spend and merges. The stricter of the organization mode and the engine mode applies.
3. Needs a human Going live is an owner or admin action. It asks you to confirm and is audited. Each engine shows a shadow accuracy report from its dry runs, so you can judge it before you flip it.
4. Guardrails (Settings > Safety): emails a day, new accounts contacted a week, ad spend a day (above it a person approves), a send window in the recipient's timezone with quiet hours, and allowed channels. A hit holds the action, raises an alert and runs it later by itself. It never drops it. Held actions are listed with a Cancel button.

One rule is not configurable: the first message or meeting invite to someone nobody has ever written to is never sent automatically, whatever the autonomy setting.

Proof library and claims Needs a human

Goal: nothing you send states a fact you cannot back up.

1. Settings > Proof library, add proof: case studies, metrics, testimonials and logos. Give each a permission (public, anonymized or internal only) and an optional expiry.
2. Or upload a document. Claims are extracted and kept only when the quote is verbatim in the source and any numbers appear in that quote.
3. A second person activates each proof (four-eyes). Customer phrases mined from your calls, replies and won deals are approved one by one.
4. Claims check (same page): choose the policy. Block is the default: an unbacked claim stops the action. The alternative routes it to an approver, who acknowledges each claim in the claims panel (the proposer and the agent cannot). An acknowledgement is recorded.

Settings pages that shape reporting and rules

Goal: know what each less obvious page controls before you change it. Most are for owners and admins, and the server enforces that.

Money Settings > Money

Your money definitions, which every report, dashboard and agent uses. Where does revenue truth live? picks the one source of money truth (your CRM deal amounts, or a warehouse or billing object), and revenue numbers and attribution are reconciled against it. Attribution sets the window and the model (see Attribution). Currency and FX rates sets the reporting currency and whether market rates or your finance team's dated rate sheet apply, with the drift between the two shown. Reconciliation compares your revenue truth source with the CRM's won-deal amounts (there is nothing to reconcile while the CRM is the truth). Your words for deals holds your deal types and the raw CRM values that mean each one, so synced deals are typed automatically; removing a type never rewrites deals, they show as retired.

Journeys Settings > Journeys

The lifecycles companies, people and deals follow, each with its funnel, and the stage maps that say what each CRM or source stage value means. Choose for each value: map it to a journey stage, ignore it, or ask GTM OS to guess. Saving a journey proposes a change in dev that a different person approves, then it is signed and promoted like any definition. A mapping decision takes effect at once and is applied again to the records carrying the value. A value no map knows reads Needs you, and its records keep their stage until someone decides.

Brand and compliance Settings > Brand & compliance

Three cards, all human-only to change. GDPR mode: when on, every outreach send on any channel and every contact enrichment needs a lawful basis recorded for that channel (on the contact's Consent tab); when off, only a withdrawal, a refusal or an expiry blocks a channel. Buying roles: the roles a person can hold on a deal and at their company. The defaults are there for every workspace and you add your own; deal contacts and account roles must use one of them, and removing a role never rewrites stored records. Brand safety: your voice, words to avoid, claims no draft may ever make, and voice samples. Every outreach message and SEO or GEO draft is scanned after it is generated, and a violation blocks the send or publish with the reason and a Regenerate option. Try it scans any text you paste.

Navigation Settings > Navigation

Owners and admins turn whole tab groups (Engines, CRM, Integrations, Operate, Apps) on or off for the workspace. A hidden group disappears from the sidebar for every member, not only for you. Mission Control, Approvals and Settings cannot be hidden.

Feature flags Settings > Feature flags

Per-organization flags read by the API, the worker and the MCP server. Any member can read them, and only owners and admins change them. A value is free-form JSON, so a flag can hold a switch, a number, a string or a small configuration object. Examples you meet in this guide are signals.reaction, signals.scan and the nav.section.<group> flags that Navigation writes.

Notifications Notifications

Open it from the bell in the header. Your own list of tasks assigned to you, due dates, approval requests and setup reminders, with Load more and Mark all read. At the top is your own switch to also receive setup reminders by email, at most once a week; it needs the instance email transport (see Email for invitations, password reset and nudges).

Adapters CRM > Adapters

The adapter builder for a source. Introspect a connected source, audit completeness first, review every proposed field mapping with its confidence, answer the numbered questions, publish the signed mapping through the usual definition flow, start its nightly and incremental syncs, and read or download the mapping document.

Data health

Described under Run the system day to day.

Environments and going live

Goal: config moves from dev to prod safely. Every org has dev, staging and prod. The runtime reads prod. Effects in dev and staging go to a sink.

1. The environment switcher in the console header picks which environment you view (default prod).
2. CRM > Environments, Go live card:
   • Needs a human Review & sign all proposed (N): someone other than the proposer (and other than the person whose agent proposed) signs.
   • Promote dev → prod: proposes one approval for everything signed; another member approves and executes it.
3. Same from a terminal:

   gtm definition sign-all --env dev
   gtm promote --all dev prod --preview
   gtm promote --all dev prod

4. One resource only, or roll back:

   gtm promote definition.lane primary-email dev prod
   gtm rollback definition.scoring_model default --to-version 3 --env prod

Packages

Goal: install, enable and upgrade engines, screens, connectors and modules.

1. Settings > Packages. Tabs: Installed and Available.
2. Install: Available, Install (a proposal).
3. Enable or disable per environment with the toggle on the installed package (a proposal).
4. Upgrade: Preview upgrade vX -> vY (changes, breaking or not), then Propose upgrade to vY.
5. Remove: Uninstall, then Propose uninstall (your data is never deleted).
6. Needs a human Another admin approves each in Approvals.

CLI equivalents:

gtm pkg enable <name> --env <env>
gtm pkg upgrade <name> --dry-run

Engine app updates. Settings > Packages shows a card when engine apps have updates. An upgrade of GTM OS never changes an installed engine app by itself. An owner or admin proposes the update (one approval), edits your workspace made to the app are merged in, and if an edit overlaps the release that app is not updated and you choose Keep mine or Take new. Every update is a new config version you can roll back.

Self-host on a server

Goal: people reach GTM OS at https://app.acme.com while the instance stays closed to everything except your proxy.

Put a reverse proxy in front (recommended)

1. DNS and firewall Needs a human: point app.acme.com (console), api.acme.com (API) and, if coding agents outside the server need it, mcp.acme.com at the server. Use one parent domain so the login cookie is shared. Open only ports 80 and 443. Do not open 3000, 3001, 3004 or 5432.
2. Keep GTMOS_BIND_ADDRESS=127.0.0.1, and set the public URLs in .env (the origins a browser really uses, with https:// and no trailing slash), then run gtm up again:

   PUBLIC_API_URL=https://api.acme.com
   PUBLIC_CONSOLE_URL=https://app.acme.com
   PUBLIC_MCP_URL=https://mcp.acme.com

3. Proxy each host to its local port. With Caddy (it gets and renews the HTTPS certificates) the whole Caddyfile is:

   app.acme.com {
       reverse_proxy 127.0.0.1:3000
   }
   
   api.acme.com {
       reverse_proxy 127.0.0.1:3001
   }
   
   mcp.acme.com {
       reverse_proxy 127.0.0.1:3004
   }

   nginx works the same way: one server block per host with proxy_pass to its local port, the Host and X-Forwarded-Proto headers, and the Upgrade headers for the console.
4. Check it:

   curl https://api.acme.com/health
   curl -I https://app.acme.com
   ss -tlnp | grep -E ':(3000|3001|3004|5432)\b'

Open the ports on purpose instead

Edit GTMOS_BIND_ADDRESS in .env and run gtm up again, or create the instance with gtm up --bind 0.0.0.0. gtm up rewrites docker-compose.yml on every run, so never edit the compose file to open or close ports. The .env value is kept across runs. A --bind flag passed to an existing instance is ignored and reported, because the existing .env wins.

Upgrading an older instance

The first gtm up or gtm upgrade on 0.2.5 prints a warning when your .env has no GTMOS_BIND_ADDRESS, and writes 127.0.0.1 into it so the choice is explicit from then on. If a teammate's browser, a webhook or an MCP client on another machine was reaching the instance by IP address, choose a reverse proxy or 0.0.0.0 as above.

Security defaults an operator must know

Goal: know what is closed by default and the few settings that change it.

Upgrade GTM OS

Goal: move your instance to a newer release without losing anything. An upgrade never touches, removes or loses your data. Every release only adds (new tables, nullable or defaulted columns, indexes). The updater refuses any release that does not, and there is no override.

Which version am I on?

The CLI version and the instance version are separate things. gtm upgrade --check shows both, plus what the signed release list offers, and changes nothing. Releases before 0.2.5 published images only as 0.2.2 and stable. CLI versions 0.2.3 and 0.2.4 shipped no images, so an instance installed with either still runs the 0.2.2 images.

1. Upgrade the CLI first. It renders the compose file your instance runs on, so it must be at least as new as the release you move to. If it is too old, gtm upgrade stops and tells you which version to install.

   npm i -g @gtmos/cli@latest

2. See what is available (from the instance folder, or add --dir <path>):

   gtm upgrade --check

3. Rehearse. It prints every command and changes nothing:

   gtm upgrade --channel stable --dry-run

4. Upgrade. --yes is required because it migrates your live database:

   gtm upgrade --channel stable --yes

5. In Claude Code run /mcp to reconnect, then refresh your project files in each project folder:

   gtm init --refresh

What happens, step by step

1. The signed release list is fetched and its signature checked. The path is planned by its rules: no downgrade, no skipped required stop, additive-only releases, a minimum CLI. Any failed check refuses the upgrade before anything is pulled.
2. Preflight: one update at a time, and free disk at least twice the database size plus 2 GB.
3. The target images are pulled, and each digest must match the signed digest.
4. The additive-only guard reads every pending migration and refuses anything that drops, renames, retypes, deletes or overwrites.
5. The API, worker, MCP and console stop gracefully. A backup is taken and read back to verify it.
6. A rehearsal restores that backup into a scratch database, migrates it and compares it with your live data (tables, columns, types, row counts, row checksums). Any difference refuses the upgrade.
7. The version is pinned in .env, the migration runs inside the new image, services start, and health and schema are verified. The newest five backups are kept.

What is preserved

• All your data: records, history, definitions, approvals, connections and keys.
• Your apps and configuration. An upgrade changes no installed engine app. See Packages for engine app updates.
• Your GTMOS_MASTER_KEY. Backups do not contain it. Keep it safe, apart from the dump.

Rollback

A failed upgrade rolls back by swapping the images back: the previous compose and .env files and the previous images are restored and the services restart on them. The database is never restored, dropped or recreated by an upgrade, and the verified backup is kept. This works because every migration is additive, so the previous code runs on the migrated database.

Restoring a backup is a manual last resort, for example if something other than the upgrade damaged your data. Never restore over the live database: rename it first, then restore into a new one. gtm upgrade --help prints the exact commands.

Moving to 0.2.5 from 0.2.2 (or CLI 0.2.3 or 0.2.4 on 0.2.2 images)

• Upgrade the CLI first. This is not optional.
• Ports become local-only. See Self-host on a server. If people or systems reach the server by IP address, choose a reverse proxy or GTMOS_BIND_ADDRESS=0.0.0.0.
• Read Security defaults: GTMOS_LIVE, instance keys, CSV import permission, private records.
• Account scores can move once on the first rescan (preview it). Visits from AI assistants move from "Website (other)" to SEO & GEO credit. New workspaces start with the signal verification gate on Strict.
• Run gtm init --refresh in each project folder for the new skills and subagents.
• You are already on a newer 0.2.x? The path is the same. If a release in between is marked as a required stop, gtm upgrade plans it as an extra hop and takes a backup at each hop.

Check it worked

1. gtm doctor shows the sources you expect as live, and its Harness section has no stale line.
2. GET /health reports the new version on the API, worker, MCP server and console.
3. The upgrade reported that verification passed, and a snapshot exists in your backups folder.
4. Row counts of your main tables match what you noted before.
5. A rescan preview looks reasonable before the first rescan.
6. Dry Mode send check: propose one send to an internal address and confirm that a different person has to approve it.
7. Settings > Proof library: add one proof and check the claims check passes and blocks as expected.

With the updater service installed (gtm updater install), instance admins can also update from Settings > Updates.

Backup, export, restore and verify a release

Goal: know what is backed up before an upgrade, how to take your own copy, how to leave with an organization's data, how to restore by hand if you ever must, and how to check that a release is the one that was published.

The backup an upgrade takes

Every gtm upgrade stops the API, worker, MCP server and console, then writes a full-instance backup of the database (every organization in it) as a compressed pg_dump file, backups/gtmos-pre-upgrade-<stamp>.dump in the instance folder. It is read back to prove it is readable, and a rehearsal restores it into a scratch database, migrates it and compares tables, columns, types, row counts and row checksums with your live data. Next to it the upgrade keeps .env.pre-upgrade-<stamp> and docker-compose.yml.pre-upgrade-<stamp>. The newest five are kept. The backup is never used automatically: a failed upgrade swaps the images back and leaves the database alone.

Take your own backup

There is no gtm backup command in 0.2.5. The upgrade uses pg_dump in custom format run inside the Postgres container, and you can run the same from the instance folder in a POSIX shell (the redirect corrupts a binary file in Windows PowerShell):

mkdir -p backups
docker compose --env-file .env -f docker-compose.yml exec -T postgres pg_dump -U gtmos -d gtmos -Fc --no-password > backups/gtmos-manual.dump

Keep the master key apart

A dump does not contain GTMOS_MASTER_KEY. Every stored credential (connections, OAuth tokens, SSO secrets) is sealed with that key, so a restored database without it cannot decrypt them. Copy the key from .env into a password manager or secret store when you install, and again whenever you change it, and keep it somewhere other than next to the dumps. The dump itself is not encrypted and contains personal data, so protect the folder it lives in.

Restore by hand (last resort)

Never restore over the live database, and never as a reflex: an upgrade does not need it. If data was damaged by something other than an upgrade, keep the current database first, then restore into a new one. gtm upgrade --help prints the exact commands. In short, from the instance folder:

1. Stop the services, and rename the live database so nothing is lost:

   docker compose --env-file .env -f docker-compose.yml stop api worker mcp console
   docker compose --env-file .env -f docker-compose.yml exec -T postgres psql -U gtmos -d postgres \
     -c "ALTER DATABASE gtmos RENAME TO gtmos_before_restore_<stamp>"
   docker compose --env-file .env -f docker-compose.yml exec -T postgres createdb -U gtmos -O gtmos gtmos

2. Restore in three sections, with one repair between the first two (a function that a 0.2.2 check constraint calls needs its search path set), using the dump you chose:

   docker compose --env-file .env -f docker-compose.yml exec -T postgres pg_restore -U gtmos -d gtmos --section=pre-data < backups/gtmos-pre-upgrade-<stamp>.dump
   docker compose --env-file .env -f docker-compose.yml exec -T postgres psql -U gtmos -d gtmos \
     -c "ALTER FUNCTION public.is_valid_record_link_object_type(uuid, text) SET search_path = public"
   docker compose --env-file .env -f docker-compose.yml exec -T postgres pg_restore -U gtmos -d gtmos --section=data < backups/gtmos-pre-upgrade-<stamp>.dump
   docker compose --env-file .env -f docker-compose.yml exec -T postgres pg_restore -U gtmos -d gtmos --section=post-data < backups/gtmos-pre-upgrade-<stamp>.dump

3. Put .env and docker-compose.yml back from their .pre-upgrade-<stamp> copies, then docker compose --env-file .env -f docker-compose.yml up -d. The renamed gtmos_before_restore_<stamp> database stays until you drop it yourself.

Go back to the previous release after a successful upgrade

You do not need a database restore. Every release migration only adds things, so the previous release runs on the migrated database. From the instance folder, using the oldest stamp from that upgrade run:

docker compose --env-file .env -f docker-compose.yml stop api worker mcp console
cp .env.pre-upgrade-<stamp> .env
cp docker-compose.yml.pre-upgrade-<stamp> docker-compose.yml
docker compose --env-file .env -f docker-compose.yml up -d
gtm upgrade --check

Use docker compose and not gtm up, which renders the compose file again and replaces the copy you just restored. The previous images must still be in the local cache or on the registry, and a pulled image must match its signed digest, so do not remove old images until you are sure.

Export one organization: gtm org export

gtm org export --org <id> --out <dir> [--format parquet|sql] [--env <env>] [--dry-run] [--database-url <url>]

• It writes a portable bundle for one organization: one Parquet file per organization table (the default), or with --format sql a single dump of column-by-column INSERT statements. It also writes a manifest that lists each table with its row count and file, and records that the export was scoped to the one organization.
• With --env and GTMOS_API_URL set, it adds the configuration of that environment as config files (your definitions and settings).
• It connects as the restricted application database role (DATABASE_URL, or --database-url) with the one organization selected, so row-level security applies and it can only read that organization's rows. It does not read user accounts or sessions, and it only reads: it never changes the database.
• --dry-run prints the plan and writes nothing.

Verify a release

• The signed release list. Releases are announced in releases.json, signed with an ed25519 key (releases.json.sig). The CLI trusts only the release keys built into it. The default address is https://ay-automate.github.io/gtmos-releases/releases.json, and GTMOS_RELEASE_MANIFEST_URL overrides it (an air-gapped site serves a mirrored list that is still signed).
• What the list says. For each release: the version, date and channel, whether it is a security release, the minimum CLI version, the oldest version it can be reached from, any required stops, whether it is additive-only, and the sha-256 digest of each of the api, worker, mcp and console images. A list may claim at most 90 days of life.
• What the CLI checks, before anything changes. The signature, the schema and the expiry; the path (no downgrade, no skipped required stop, additive-only releases, a minimum CLI); that the images come from an allowed registry (ghcr.io/ay-automate unless you mirror); and after the pull, that every pulled image's digest equals the signed digest. Any failure refuses the upgrade.
• Check it yourself. gtm upgrade --check fetches and verifies the list and prints what it offers, and changes nothing. To check an image by hand, pull it and compare its registry digest with the one in releases.json for that service.

Your own cloud (BYOC)

gtm byoc plan|apply|destroy --cloud aws --region <region> provisions one GTM OS instance in your own AWS account with Terraform (or OpenTofu 1.6 or later): a managed Postgres database, the api, console, worker and MCP services on ECS with a one-shot migration task, an object bucket, Secrets Manager and a load balancer. It uses the same four images and secrets as self-host. Honest scope: AWS is the only cloud. plan works offline without cloud credentials and shows what it would create. apply and destroy refuse to run without --yes, real credentials and Terraform installed. The installer and its dry run are built and tested, but a live deployment into a real AWS account has not been performed. A runbook exists in the product repository; it is not part of these public docs.

Troubleshooting

Errors carry a remediation field: read it first. If nothing matches, ask your agent to read docs/gtmos/guides/08-troubleshooting.md.