Teams & remote (overview)

askTheodor starts as a single app on your own computer, but it doesn’t have to stay there. A team in askTheodor is still local-first — there is no askTheodor cloud you log into. Instead, the model is a shared, self-hosted hub (or several) that runs your AI workforce around the clock, plus one or more operator machines that connect to it to steer the work. You own every box; the app just keeps them in sync.

Status: partly shipped

The foundations here — the headless runner, peer pairing, sync, the Fleet screen, and instance role declaration — are shipped. The richer team features (master/secondary delete approval, server-side role enforcement, the full two-stage outreach chain) are in progress and called out on each page. This section documents the intended design and flags what is and isn’t live yet.

The two kinds of instance

Every running copy of askTheodor in your team is one of two kinds:

• Command Center — a normal, local desktop install of the full app, used by one operator (you, or a teammate). It has every screen: Chat, Companies, Plans, Library, Fleet. It’s the cockpit you drive from, and the place where sensitive things — sending email, approving deletes — actually happen.
• Team-Hub — a headless copy started with asktheodor --runner, usually on a server (a VPS) you rent. It has no window and nobody sits at it. It runs your workhorse workers 24/7: research, development, writing, design, digesting. The Team-Hub is the paid “remote” add-on.

You can think of it as a workshop: the Command Center is where you stand and direct; the Team-Hub is the production floor that keeps running after you go home.

How they connect

Instances find each other through pairing — the same secure handshake you’d use to link two desktops. Once paired, two background jobs keep everything coherent:

• Sync mirrors the shared workspace — Companies, Workers, Library, Plans — row by row, in both directions, so every machine sees the same world.
• Report has each instance ping the others with a heartbeat and status, so the Fleet screen shows who’s online and what they’re doing.

The mechanics live in Fleet & sync; the practical setup is in Deploy to a VPS.

The shapes a team can take

There are really only three situations to understand:

1. One Command Center + many Team-Hubs. The simplest team, and it needs no extra setup. Your one desktop is implicitly in charge; the hubs do the heavy lifting. Pair them, push your provider keys, and go.
2. Many Command Centers + many Team-Hubs. Now teammates each have their own desktop on the same shared hubs. Everyone syncs and keeps working — but exactly one Command Center must be designated the ⭐ Master. The Master is the only one allowed to permanently delete shared Companies or Workers off the hubs; everyone else’s delete becomes a request for the Master to approve. See Roles & the Master.
3. A Team-Hub alone. Perfectly fine to run a hub with no Command Center attached for a while — it keeps syncing and running Plans. You just can’t steer it or send anything out until a Command Center connects, because sending only ever happens from a Command Center.

Start small

You don’t need the team machinery to benefit from a hub. Begin with one Command Center and one Team-Hub: that alone gives you a tireless 24/7 worker with zero role configuration. Add more desktops — and a designated Master — only when real teammates join.

What stays true no matter the size

• Local-first. Your data lives on machines you control. Nothing routes through an askTheodor server.
• Hubs never spend money and never send outreach directly. A hub drafts; a human approves; a Command Center sends. This is the no-send guarantee — see Outreach approval.
• One kill-switch. Pausing autonomy from a Command Center is designed to reach every hub, so you can halt the whole fleet at once.

Where to go next

• Command Center vs Team-Hub — what each kind is for, in depth.
• Roles & the Master — declaring this machine’s role and the delete-approval rule.
• Outreach approval — the no-send guarantee for hubs.
• Deploy to a VPS — stand up a Team-Hub over SSH, step by step.

In practice

The reason to add a hub is time, not headcount. A single operator with one always-on machine already gets the main benefit: routines that fire at 6am whether or not your laptop is open, Plans that keep advancing while you’re in meetings, long research sweeps that don’t tie up your desktop. You don’t need teammates to justify a hub — you need work that shouldn’t wait for you.

Start with case 1 and don’t configure roles. One Command Center plus one Team-Hub needs no master, no role declarations, no permission thinking. Pair them, push your provider keys, and the hub starts carrying the unattended work. Reach for the master/secondary machinery only when a second person’s desktop joins the same hubs.

What actually changes when a second operator arrives is deletes. Sync mirrors everything, so a hard-delete on one desktop would otherwise propagate everywhere — including over a colleague’s in-flight edit. That’s the entire reason for the ⭐ Master rule, and it’s worth reading Roles & the Master before the second desktop pairs rather than after.

Read the status notes on these pages literally. The foundations — headless runner, pairing, sync, Fleet, role declaration, draft-only channels — are live. Parts of the richer team model are still in progress and flagged per page. Where something is marked in progress, treat the role model as a strong convention you should follow, not a guarantee the software enforces for you yet.

Local-first survives the jump to a team, but note what that means for the hub: it’s a machine you rent and administer. Nothing routes through an askTheodor server, and equally, nobody else is patching your VPS or backing it up. Take a backup before you make the hub authoritative for anything.

🎓 Learn it hands-on: Fleet: a Team-Hub on a VPS

Terms in this page

• Local-first — your data lives on devices you own (a local database) rather than on a vendor’s server; a team keeps this property by self-hosting the shared hub instead of using a cloud.
• Instance — one running copy of askTheodor. Each instance is either a Command Center or a Team-Hub.
• Command Center — a full desktop install of askTheodor used by one operator; the cockpit you steer from and the only place sends and final approvals happen.
• Team-Hub — a headless, 24/7 copy started with --runner (usually on a server) that runs your workhorse workers; the paid “remote” add-on.
• Runner — headless mode (asktheodor --runner): the app with no window, suitable for a server.
• Operator — the person sitting at a Command Center, directing the work.
• Pairing — the secure handshake that links two instances so they may sync and delegate to each other.
• Sync — the background mirroring of the shared workspace (Companies, Workers, Library, Plans) across paired instances.
• Report / heartbeat — the periodic status ping each instance sends so the Fleet screen knows who’s online and busy.
• Fleet — the screen that shows every paired instance, its status, and the controls to delegate and manage them.
• Master (⭐) — the one Command Center designated to approve permanent deletes on the shared hubs.
• Outreach — anything sent or posted outward (email, a reply, a DM); hubs only ever draft it.
• Kill-switch — the single autonomy-pause control that halts all unattended work, designed to reach every hub in the fleet.