Install
Download the latest release from GitHub releases and drag Bloks to Applications. The app is code-signed and notarized, so it opens on the first try instead of being blocked. It is universal: Apple silicon and Intel.
Building from source works too and takes about four minutes:
git clone https://github.com/hamedgitty/bloks
cd bloks
pnpm install
pnpm dev:server # the harness
pnpm dev # the app
pnpm dev:desktop # the desktop window
Everything Bloks stores lives on your computer, starting with one folder, ~/.bloks, which holds your Personal workspace. Remember that path; it comes up again at the bottom of this page.
Engines
An engine is what an agent thinks with. Bloks ships with no model of its own on purpose: you bring the one you already pay for, and each agent picks its engine and model individually.
CLI agents
If Claude Code, Codex, Gemini CLI, OpenCode, Grok CLI or Antigravity is installed and signed in, Bloks finds it and it just works. These run tools: they execute commands, read and write files, and act.
Nothing installed yet? The first-run check and Settings, Engines and keys have an Install button for Claude Code, Codex, Gemini CLI, Pi, Antigravity and the Grok CLI. It installs into your own folder, so there is no password prompt and no permissions error, and if it cannot finish it says what to do next. An engine that is installed but not signed in says so; Sign in opens Terminal at its sign‑in, and the row turns green once you are done.
API keys
Paste a key in Settings, Engines and keys for Gemini, Grok, Kimi, Llama, DeepSeek, Mistral or Groq. These engines get a tool loop from Bloks itself, so they can still ask you questions, run sandboxed commands and request app connections. OpenRouter signs in from your browser instead of a key.
Local models
Run Ollama and Bloks lists whatever models it serves. Whether a local model can run tools depends on the model, so Bloks makes no promise there and marks it accordingly.
You can switch an agent’s engine mid‑conversation. Bloks replays the story so far to the new engine, so nothing is forgotten in the move.
Bloks AI
New in Bloks 3.
With Bloks AI on your plan, an agent can run with no key and nothing to sign in to: pick Bloks AI as its engine, which is Bloks’s own. Claude Code is the exception: it always runs on your own Claude plan or API key, never on Bloks AI, so sign it in under Settings, Engines and keys. What is left of the month shows as a meter in Settings, Plan and on the Usage page, with top‑ups when you want more, and the message box says when it is getting close. Work nobody asked for, like the nightly memory tidy, uses it only when you switch on Let background work use Bloks AI. Which models run it, how the allowance is counted and where requests go are on its own page.
Engine scout
New in Bloks 2.3.
Settings, Engines and keys shows how often each engine's work is kept, learned from what you do with it: a change you undo, a conversation you rewind past or a rehearsal you discard counts against it. When a lighter model has been doing as well for an agent over enough turns, its settings say so with a button to switch. It is worked out on your Mac and nothing switches on its own.
A backup engine
New in Bloks 2.2.
Subscriptions and keys run out: a usage limit until the afternoon, a rate limit, no credit left, an outage. In an agent’s settings, pick a Backup engine. When a turn fails because the main engine is out, the backup picks up the same message with the conversation so far, and the chat says what happened.


- Only when the engine is out. A failed test or a refused command is still a failed turn. The backup takes over for limits, lack of credit, overload and sign‑in problems, not for the work going wrong.
- It goes back by itself. The engine that ran out rests until it said it would be usable again (or a sensible while when it did not say), for every agent on it. After that each agent returns to its own engine.
- Once per message. If the backup is out as well, you see why, rather than Bloks trying engines in a loop.
Your first agent
Press ⌘N or the plus button. Pick a role and the agent is made on the spot, named for the job and carrying that role’s skills, or describe the job in a sentence and Bloks proposes a name. Every agent gets a pixel face; tap it to shuffle, or open its settings to pick shape, color and expression yourself. The same editor exists on the iPhone.
An agent you make from a role opens with that role’s own first question. Your answer is simply the first thing you tell it, and you can change how it works later in its settings.
Where new agents start
Settings, New agents sets the folder, approvals, model and effort every new agent starts with, whether you hire it or one of your agents does. It applies before the first turn, so the first chat already runs in the right folder. Choosing Auto for approvals asks for Touch ID, and an agent that hires another never hands on more approvals than it has itself.
Talking and tasks
Type like you would to a person. While an agent works you see what it is doing: its tool calls fold into one quiet line (“Ran 4 commands, read 6 files”) that opens to the full list, and its avatar changes state in the sidebar.
- Parallel tasks. An agent keeps up to twenty lanes open, each its own conversation. Tabs at the top of the window show each lane with its state; new lanes name themselves after the first thing you ask, and a double click renames one. Any lane can be closed; closing the last starts a fresh one. A routine can run in a lane of its own, so two routines do not share a context.
- Steering. A message that waits for a busy agent, as a new request does (see Messages while it works below), is marked in the thread and starts its own turn the moment the current one settles. If Bloks restarts in between, the message still goes once it is back, as long as it was sent in the last twelve hours; an older one is marked Not sent with a Send again button rather than acted on late.
- Long conversations. New in Bloks 2.5.20. Scroll up and earlier messages load as you go, with your place kept; the button at the top is still there if you prefer it.
- Approvals. Anything consequential stops and asks first, as a card with one‑tap answers, on the Mac and on your phone.
- Replies and forwards. Hover a message to reply with context or forward it to another agent, like any messenger.
- Artifacts. Files an agent saves during a turn appear as cards: HTML renders live, spreadsheets and documents open in a native viewer.
- Search. ⌘K searches every conversation, every lane, every room.
- Skills by name. Type
/in a message and pick from the agent’s skills, the ones from your library and, for Claude Code agents, the ones installed for Claude Code itself. The skill is highlighted in the message so you can see it will be used. - Undo. Every turn that changes files ends with a card listing them, and one button puts them back. See Undo.
- Rewind. Hover a message you sent and press the clock to take the conversation, and the files, back to before it. See Rewind.
- Rehearse. Press the flask beside the microphone and the agent works on a copy of its folder, for you to apply or discard, or to compare with other agents. See Rehearsals.
- Answers you can use. New in Bloks 3. An agent can answer with cards, tables, charts, metrics, steps, tabs, forms and buttons, drawn as the reply arrives, instead of a wall of text. A click can answer the agent, open a page or change the answer itself; nothing in an answer fetches anything. Switch it off for an agent with Interactive answers in its settings.
- The answer first. New in Bloks 3. An agent’s first sentence is the answer, with no tips or sign‑offs nobody asked for. A comparison, prices or options to choose between come back in the chat as an answer you can use, not as a file, and when an agent did make a file, its reply is a sentence or two: what it is and its headline.
- Pages that look finished. New in Bloks 3. Before an agent makes a page, a report, a dashboard or a deck, it reads the built‑in Page design skill: the answer on the first screen, depth that follows what is at stake, and a page that reads on a phone and in dark mode. Most answers need no file at all.
- Messages while it works. New in Bloks 3. Say something mid‑turn and Bloks reads it first: a stop stops, a correction or an answer to its question goes in now, and a new request waits for the turn to end. A quiet line under your message says which, and one press goes the other way. Settings, Behaviour chooses Automatic, Interrupt or Queue for every agent, and each agent can differ.
- A terminal. New in Bloks 3. Each agent can have up to eight shells, as tabs. Dock the terminal on any side of the chat, put it side by side with the chat, let it fill the window, or open it in a window of its own.


Every conversation in view
New in Bloks 2.5. Turn on Show conversations, in Settings, General or from the list icon beside Agents, and each agent’s conversations are listed under it in the sidebar. Each has its own unread dot and says whether it is working or waiting on you; hover an agent for a plus that starts a new one. Opening an agent always goes to the conversation that pinged you, with the view on or off. Right‑click a conversation to rename it, mark it unread, copy its ID or close it. While the sidebar lists conversations, the tabs above the chat step aside.
A row at the top of the sidebar says when anything is waiting on you: one goes straight there, several open Activity. Everything else is on the slim rail at the left edge (new in Bloks 3): Chat, Overview (the morning brief, Activity, Projects and Rehearsals), Automations (routines, watchers, intents and workflows), Memory, Plugins (apps, tool servers and skills), Usage and Settings. Settings is one list in groups, Account, Workspace, Agents, Integrations, Connections and Data, with a search that finds the very row a word lives on. ⌘K finds Settings pages too.
The chat’s sidebar, and the lists beside Settings, Plugins, Memory, an agent’s settings and Automations, can be dragged wider or narrower by their edge, or folded away. Folded, Settings becomes tabs along the top, and Plugins and Memory a small switch beside the title.

The morning brief
New in Bloks 2.3.
Each morning Bloks writes up what every agent did while you were away, what is waiting on you, and what it cost. Open Overview on the rail, where the brief comes first, or tap the notification on your iPhone.

- Every line leads somewhere. Click one to open the conversation it came from.
- Answer from it. Approvals waiting on you have Allow and Deny right in the brief.
- Listen to it. Play reads it as a round: an opening, then each agent saying its own part in its own voice, then what is waiting. On the iPhone it reads with the phone's voices, offline.
- Free and instant. It is written from what is already on your Mac, not by a model, so it costs nothing and every line is something an agent actually did.
It arrives at 08:00; change the time, or turn it off, at the bottom of the brief. A Mac asleep at that time makes it when it wakes. Ask Siri “What’s my brief in Bloks” for the headline.
Undo what an agent changed
New in Bloks 2.
Before each turn Bloks photographs the folder the agent works in, and after the turn it photographs it again. If anything changed, a card appears under the agent’s reply: every file it added, changed or deleted, with how many lines.

Click a file to see exactly what changed in it.

Press Undo, then Put them back, and every file returns to how it was before that turn: changed files are restored, deleted ones come back, and new ones are removed. The agent is told on its next turn, so it does not carry on from files that are gone.

- Nothing you did since is lost. A file is only put back if it is still exactly what the agent left. If you or a later turn changed it, it is left alone, and the card names it.
- What is tracked. The agent’s working folder, or its own workspace if it has none. Folders that tools regenerate, like
node_modules, are skipped, files over 2 MB are listed but not kept, and a home folder is never photographed. - Where it lives. The copies stay on your computer, in
~/.bloks/checkpoints. The last few hundred turns can be undone.
To stop a change landing at all, rather than take it back afterwards, rehearse it.
Undo pairs with how much an agent may do on its own. Choose it once, during setup or in Settings, Rules and approvals: Ask first before anything consequential, Accept edits so file changes go ahead and the rest asks, Auto so everything goes ahead unless a rule refuses it, or Full access, which takes the engines’ own guards off too: no prompts and no sandbox, so your rules cannot catch anything. Every new agent starts on your choice, and Move all puts every existing agent on it; any one agent can still be set differently in its own settings. Shared rooms always ask. With undo behind it, Accept edits is a comfortable default for an agent working in a project folder.
Rehearsals
New in Bloks 2.1.
Undo takes a change back after it lands. A rehearsal stops it landing until you say so. The agent does the task on an instant copy of its folder, and you decide what reaches the real one.
- In a chat, press the flask beside the microphone. The bar above the message says the next task will be rehearsed. To compare, pick up to two other agents under Compare with.

- Send the task. Each agent gets a copy of the folder and a task lane of its own, named Rehearsal, and works there exactly as it would in the real folder. The real folder does not change.
- When it finishes, the lane ends with a card that says what would change, file by file, with each file’s diff. Press Apply to write it into the real folder, or Discard to let it go.

- To compare, open Overview on the rail and find Rehearsals. Every attempt at the same task sits side by side with what it changed and what the agent said about it. Applying one discards the others.

- Nothing you did meanwhile is lost. Apply writes each file only if the real one is still as it was when the rehearsal began. A file you changed in the meantime is left alone and named.
- Keep refining. A follow-up message in a rehearsal’s lane works on the same copy, and a fresh card replaces the last one. Once an attempt is applied or discarded, its copy is gone and the lane says so.
- Applied is undoable. After you apply, the card works like any other undo card.
- Copies are cheap. On a Mac the copy shares storage with the original until something changes (and on Linux filesystems that support it), so even a large project copies in a moment. Copies are removed when you decide, or after a week.
- Only the folder is rehearsed. Anything the agent does outside it, sending a message, pushing a branch, deploying, is as real in a rehearsal as anywhere. The agent is told so, and approvals still ask.
Rewind a conversation
New in Bloks 2.2.
Sometimes the conversation went the wrong way three messages ago. Hover a message you sent and press the Rewind to here clock.

- The conversation goes back. That message and everything after it are taken back, and the agent starts a fresh session that has heard only what is left.
- So does the folder. Every file the agent changed since that message is put back, newest turn first. A file you edited yourself since is left alone, and the note in the chat names it.
- Your words come back. The message you rewound to returns to the box, to send again as it was or change first.
- Nothing disappears silently. What was rewound folds into one line you can open to read.

Rewind works in a conversation with one agent. The agent’s memory notes are not changed by a rewind; the Memory panel has its own undo for those.
Rooms and teams
A room is a group chat of agents. Address one with @name, or just talk and the room decides: juniors answer first, whoever you made most senior speaks last and can delegate with @name itself. Rooms can also be lead‑only, where unaddressed messages go straight to the senior agent.
The team library ships six premade teams, each with roles, seniority and skills. Hiring one asks whether to reuse agents you already have or mint new members with fresh names. Custom rooms you like can be saved back into the library and rehired later.
Add to Bloks. New in Bloks 2.3. Every team in the gallery has an Add to Bloks button that opens the app with the team ready to hire.
Teams as files. New in Bloks 2. A team is one Markdown file: a heading per member, its seniority, look and skills as a few lines, and its brief as the body. Export any room as a team file from the room's ··· menu, import one with Import a team file in New room, or hire from the gallery, which is also listed in the Team library under From the gallery. Every file opens in the same hire dialog as a premade team, so nothing is made until you have chosen the seats.
Agents working together
Agents do not only answer you. During each turn an agent can use bloks, a command that acts on your workspace as that agent, with a credential that ends with the turn. It reaches only what an agent is allowed: never your settings, your keys or another agent’s conversations, and only the rooms it is in. Running it is a command like any other, so an agent that asks before running commands asks before this one too.
- Talk to each other. One agent messages another with
bloks say. Both chats show a compact row that opens the whole exchange between the two. A message to an agent in the middle of a turn waits for that turn to end, and the sender is told so. - Build a team. An agent can hire a teammate, open a room, file agents into sidebar sections and post work on the job board.
- Stop a teammate. New in Bloks 2.5.22. With
bloks stopan agent can stop the current turn of an agent it hired, or of one it outranks in a room they share. Its reason is the next thing that agent hears, and the chat says who stopped the turn. No other agent can. - Read a room. New in Bloks 2.5.22. An agent can read the recent messages of a room it is in with
bloks history, so it joins a discussion knowing what was said. - Remember.
bloks recallsearches an agent’s own past conversations for a decision, a name or a number. Each result says whose words it holds, yours, a room member’s or another agent’s, so a report from another agent is never taken for your decision (new in Bloks 2.5.21). A result cut short can be read in full withbloks recall --id(2.5.22). - Schedule itself. Routines, one‑time routines and watchers, the same ones you make; see Automations.
- Look after its conversations. An agent can rename or close a conversation it is in, and start it on a fresh engine session with
bloks fresh(new in Bloks 2.5.21) when a long session has grown slow and expensive. The conversation stays as it was; the next turn simply starts without the old context, so the agent saves anything it needs to its memory first.
Workspaces
New in Bloks 3.
A workspace is a whole Bloks of its own: its own agents, memory, keys, rooms, routines and settings. Keep your own agents in Personal, your company’s in Business, and a client or a side project in one with a name of its own. Nothing moves between them, so the agents in one never read another’s notes.
- The switcher. The workspace you are in sits at the top left of the window, with its mark. Click it for every workspace, with a dot where something is waiting, then Join a workspace, New workspace, Workspace settings, Plan and Mute. ⌘1 to ⌘9 jump straight to one, and so does ⌘K.
- In your order. Hold a workspace in the switcher and drag it, or press ⌥ with the up or down arrow. Everywhere workspaces are listed, they follow the same order.
- A new workspace. Choose Business or a name of its own, who uses it (Just me, or Team to invite people, which needs Bloks Team), and its mark. It opens on a short welcome that follows what you chose: inviting people for a team, its name and logo for a business, and nothing about members when it is just you.
- Marks you choose. A mark is a colour and a shape. Pick both for any workspace of yours, Personal and Business included, from the Mac or the phone, or press Shuffle; a choice another workspace on your computer already wears is shown but not offered, so no two look the same. An owner can upload a logo instead. On a workspace you joined, the mark you pick is yours alone, and nobody else in it sees the change.
- They keep working. Every workspace runs whichever one you are looking at, so routines and watchers keep their times, and a question or an approval in one you are not looking at still reaches you. The Dock badge counts them all.
- Mute and notifications. Mute a workspace for 15 minutes, an hour, 3, 8 or 24 hours, or until you turn it back on: it keeps working, without a sound. Its Notifications page chooses what it tells you about: all activity, only when it needs you (approvals and questions), or nothing.
- Reachable online. With Bloks Cloud, each workspace has its own space and its own switch, so your phone, a browser and the people you invite reach it from anywhere. Bloks Cloud keeps three workspaces online at once and Bloks Team all of them; turning one off frees its place. One key covers every workspace on the computer, so putting another online needs nothing typed.

Workspace settings has four pages: General (its name, kind, who uses it and its mark), Members, Reachable online and Notifications. They sit in Settings under Workspace, with the workspace’s name beside it. One plan and one Bloks key cover every workspace on the computer, so Your plan is the same wherever you open it. Your phone stays paired with the workspace it first paired with; add your others from the phone’s workspace switcher in a tap (see Your other workspaces), or pair one from its own Settings, Phone and devices.
Personal is the folder Bloks has always used, ~/.bloks, exactly where it was: becoming a workspace moved nothing, and it cannot be deleted. Every other workspace keeps a folder of its own in the app’s own (on a Mac, ~/Library/Application Support/Bloks/workspaces).
Inviting people
New in Bloks 3, with Bloks Team.
Bring a partner, a colleague or a client into a workspace, to talk to its agents beside you. They never need an account or a plan of their own, and everything they do runs on your computer, with your engines and keys, within the limits you set.
- In the workspace, open Workspace settings, then Members, and press Invite someone. Give it a name for yourself if you like (“Sam”) and choose whether they join as a Member or an Admin.
- Send it however you like. The invite is a QR code with the workspace’s mark in the middle, an 8‑character code to read out (no 0, O, 1, I or L, so it survives a phone call), and a link that shows as an invite card in Messages, Slack and WhatsApp. All three are the same invite: it lets one person in, works once, and lasts 24 hours. Cancel it from the Invitations list any time.

- They open the link, scan the QR with the iPhone camera, or type the code in Join a workspace in the Bloks app on their computer or iPhone, then give their name, and the join password if you set one.

- Their request appears at the top of Members, with a notification. You both see the same four words: ask them to read theirs out. If every word matches, press They match, let Sam in. If any word is different, decline: someone else may have the invite.

Once they are in, the workspace opens in their app beside their own, with a short welcome and the team they can talk to.
- A join password. In Members, Set a join password asks for one more thing besides the invite. It is never in the invite, it is checked only on your computer, and five wrong tries close that invite and tell you somebody guessed.
- Approve each person. On unless you turn it off. Off, the right code (and password) lets people straight in, with no four words to check.
- On your own network. Somebody on the same wifi as your computer can join without Bloks Cloud at all; their app then reaches the workspace on that network only, and says so.
- Sealed on the way. The code sits after the
#in the link, where no server sees it, and the request to join is sealed for your computer, so Bloks Cloud, which carries it, cannot read the name or the password in it.
Members come with Bloks Team, up to ten in each workspace. If your plan lapses, members are paused, never removed: their app says so, and everything comes back with the plan.
Members and access
New in Bloks 3.
Members lists everyone in the workspace, with their role, their devices, their solo agents and what they spent this month. You are the Owner. Admins use the agents, rooms and memory, and can also invite and manage people; Members use the agents, rooms and memory. Change a role or remove someone from their row.
- Team agents. In a workspace with people, every agent has one shared team conversation, where each message says who sent it. Under Team agents, choose who can use each one: Everyone, Only these people or Everyone except, and whether admins always have access. You always do. Someone left out does not see that agent’s conversation, but still meets it in any room they are in.
- Rooms. Each room is open to everyone in the workspace or to chosen people, from the room’s Share place. People let into one room by that room’s own invite are its guests: they see that room and nothing else (see Sharing a room).
- Private conversations. Anyone who can reach an agent can also talk to it one to one. Nobody else reads that, you included, unless you turn on Owner and admins can read members’ private conversations; every member is told which way it is set. While it is on, an agent’s settings list its private conversations, to read only.
- Messages on your behalf. In a team conversation or a room, you or an admin can ask an agent to message someone (“message Sam about the draft”). It writes in Sam’s private conversation, marked as sent on your behalf. Members cannot do that to each other.
- Solo agents. Any member can make agents of their own, marked Only you: private to them, not listed for anyone else, and stored on your computer, which their app says plainly.
- Approvals. In a team conversation or a room, whoever started the work, you and your admins can answer. In a private conversation or a solo agent, its person answers.
- Limits and engines. From a member’s row: what they may spend on your API keys a month, their share of Bloks AI, how many solo agents they may make (three unless you change it), and which engines those agents may use. A member at their limit is stopped with a plain message; nobody else notices.
Members never reach your settings, your keys or your own conversations. A turn one of them starts never runs in Full access, gets none of your saved secrets, and uses your apps, tool servers or computers only where you opened them to a room. Agents share the workspace’s memory and files; each person’s notes about themselves are their own. A member can leave from their app at any time, which signs out every device of theirs and tells you.

Automations
Automations, on the rail, opens a calendar: day, week and month views, with each routine as a block you can drag to reschedule, exactly like moving an appointment. Click an empty slot to create one there.
A routine has a name, a prompt, a schedule (weekly on chosen days, or once on a date), a duration for the calendar, and a choice of where it runs: wherever the agent normally runs, its cloud computer, this Mac, or no computer. Runs land in their own background lane so they never interrupt your conversation. Missed runs fire once when the Mac wakes, or skip if too stale; they never pile up. A routine made or moved after its time of day first runs at its next time rather than at once: made at seven in the evening for six, it starts tomorrow at six (2.5.22). An agent can file a one-time routine for itself too (new in Bloks 2.5.19), to come back to something on a given day: “check whether the supplier answered on Thursday” becomes a routine that runs once and then stays on the books as a record.
Watchers (new in Bloks 2.3) share the panel too: point an agent at a folder, a web page or an RSS or Atom feed, and say what to do when it changes. “When a new invoice lands in this folder, file it.” “Tell me when this page’s price drops below $400.” “Summarise each new post.” Folders are noticed within seconds, pages and feeds every 30 minutes or as often as you set. The first look only notes how things are; a change after that gives the agent a turn in a lane of its own, or a rehearsal on a copy when you would rather check first. A page can be told to fire only when it mentions something, and no watcher starts more than six turns an hour. You can also just ask an agent in a chat to keep an eye on something; it sets the watcher up itself.
A watcher can also be a check (new in Bloks 2.5.19): a short command, run every few minutes in the agent’s folder without waking the agent, so a turn is spent only when there is something to do. The command exits 0 when it has found something (whatever it prints is passed on to the agent) and 1 when there is nothing; the same finding twice in a row is not news, and a check that hangs is stopped after 30 seconds. Because nobody is there to approve each run, a check an agent writes waits for you to approve its command in Watchers before it ever runs, unless that agent already runs commands without asking.
A watcher can speak in a conversation you name instead of a lane of its own (new in Bloks 2.5.21). Name General, and work an agent started there in the background is picked up there, with everything it already knows about it. A conversation that does not exist yet is made; one that is busy queues the watcher’s turn, just as it would your own message. Set it in Watchers, or the agent sets it when it makes the watcher.
Webhooks share the panel: each one is a URL that turns any outside event, a git push, a form, an alert, into a task for an agent. Each hook shows its delivery history, can be renamed, paused, or given a fresh URL, and the payload is always quoted to the agent as data, never as instructions.
Connecting apps
Three doors, use any of them:
- Connector cards. With a Composio key in Settings, Apps and keys, agents can request app access mid‑task: a sign‑in card appears in the chat, you tap Connect, and the task resumes itself once the connection lands. Slack, Gmail, GitHub, calendars and hundreds more.
- From your other AI apps. New in Bloks 2.3. Bloks is itself an MCP server: Claude Desktop, Claude Code or Cursor can hand your agents work, read their conversations and see what is waiting on you. It cannot answer approvals, delete anything or change settings. Settings, Apps and keys shows exactly what to paste.
- Your own MCP servers. Register any MCP server, a local command or a remote URL with an auth header, in Settings, Apps and keys, then attach it to agents individually from each agent’s settings.
- Email. New in Bloks 2.3, with Bloks Cloud. Turn it on in Settings, Chat and email and every agent gets an address like
scout.3f9a1c0b7d2e4f6a8b1c@agents.bloks.dev. Forward it an invoice, a newsletter or a thread and it gets to work in its Email lane; what it says back is emailed as the reply. You can limit who may write to a list of addresses or domains, and an agent can only reply to someone who wrote to it. Mail passes through Bloks Cloud readable, because email arrives that way, and nothing is kept on the way. - Secret cards. When a service just needs an API key, an agent can ask with a secure field in the chat. The value is stored on your Mac, handed to the agent’s tools as an environment variable, and never appears in the conversation.
Voice, calls and meeting notes
Give an agent a voice in its settings and a phone button appears. On a Mac the voices macOS ships with need no key at all (new in Bloks 2.3); ElevenLabs and OpenAI voices are there when you add a key. Calls work like calls: talk, it listens, thinks, answers in its own voice; interrupt by tapping the mic. Rooms take group calls, where saying a name addresses that member and each agent answers in its own voice, one at a time. The whole call lands in the thread as ordinary messages. Voice is marked beta while it earns trust.
Meeting notes
New in Bloks 2.3.
Press the waveform beside an agent's name and it takes notes. It listens on your Mac: your microphone, and when you switch it on, the other side of a Zoom, Meet or Teams call, from what your Mac is playing (that part needs macOS 13 and Screen Recording permission). The words appear as they are said, labelled You and Them. Transcription is Apple's, on the device; nothing joins the call as a bot and nothing is recorded.
Press Stop and write it up and the agent writes a summary, the decisions and the action items in its Meetings lane. An action item that belongs to one of your agents shows a Hand to button that gives it to that agent, with the meeting named.
Computers
Agents can have a machine of their own. Four options, chosen per agent:
- Cloud computer. A remote Linux desktop from Boat (formerly Box), with a paid API key. Bloks provisions it and shows a live preview.
- Local VM. A free Linux desktop in a container on your Mac, set up once from Settings with a guided checklist. Isolated from your own desktop, with one durable workspace folder that survives rebuilds.
- This Mac. The agent works your own screen, looking before it touches and asking before anything hard to undo.
- Sandbox. A headless container: shell and files, no display.
A cloud computer bills while it is awake, so Bloks puts it to sleep after it has sat idle for 20 minutes (change it in Settings, Computers), and wakes it before the next turn that needs it. Its files stay.
Every preview has a rewind scrubber: drag back through the last several minutes of the agent’s screen to see not just what it is doing but what it did. Opening a desktop full screen keeps a chat beside it, dockable to any edge or floating, and the close button never leaves the corner.
Memory and working folders
The Memory panel and its journal are new in Bloks 2.
Each agent keeps notes in its own workspace: MEMORY.md, loaded into every turn, plus topic files it reads when a topic comes up. All plain Markdown. Memory is capped so it stays a briefing, not a transcript, and agents are instructed never to store instructions that arrive from webhooks or forwarded content.
Open Memory on the rail to see every agent's files in one place, a Shared memory every agent reads, and About you. Edit anything, add a topic, or forget one. Recent changes is a journal of every change, whether the agent made it during a turn or you made it here, each with its diff.

Any change can be undone. Like undo for files, it only puts a file back if it is still exactly what that change left, so an edit you made afterwards is never lost.
About you, and looking back
New in Bloks 2.3.
Agents can suggest short notes about you as they learn: how you like answers, your timezone, the names you use. Nothing is added until you keep it, in Memory, About you, where you can also change the words, remove a note, or write your own. Kept notes reach every agent from then on, so a new hire already knows you, and they are never shared with people you invite into a room.
An agent can also search its own past conversations when something may have come up before: a decision, a name, a number. It only reaches the conversations it was part of.
An agent can also be pointed at a working folder, your project directory for example. Each task lane pins the folder it started in, so a lane never shifts ground mid‑conversation.
Pair your iPhone
The iPhone app is a window onto Bloks running on your computer: the same agents, their chats, and the approval cards you can answer with a tap. Nothing runs on the phone itself, so it has to be paired with the computer once. It takes about a minute.
Before you start: Bloks is open on your computer, and the phone and the computer are on the same wifi. It works the same on a Mac, a Windows PC or Linux; the iPhone app calls it “your Mac” either way. The phone’s steps below are the iPhone app 3.0’s.
On your computer
Open Settings at the foot of the rail and choose Phone and devices. Until a phone is paired, its card is Pair your iPhone, with three steps that say exactly what the phone says:
- Press Pair a phone below. It turns phone access on if it is off. The first time, the card says Restart Bloks to finish turning this on, because Bloks only starts listening on your network when it starts: press Restart now, come back to Phone and devices, and press Pair a phone again. If your computer asks whether Bloks may accept incoming network connections, choose Allow.
- On your iPhone, open Bloks and tap Scan the code. The card shows a QR code, the same code as six digits to type instead, and the address a phone typing it should use.
- Point it at the code. It works once. No code exists until you press Pair a phone. While the card is open it makes a fresh one before the last runs out, and once you close it, or the window goes, the code stops working.
When the phone arrives, the card says it is paired and becomes Phone access: the switch, your phones with the version each runs, Remove beside each one, and Pair another phone. A removed phone stops reaching your computer at once, and pairs again from the start.
On your iPhone
- Install Bloks from the App Store and open it. Until it is paired it opens on pairing: three short steps, with Paste a link and Enter a code under them.

- Tap Next to the last step, tap Scan the code and point the camera at the code on your computer. It pairs as soon as it reads it. The iPhone’s own Camera works too: point it at the code and tap the Bloks banner, and Bloks asks to pair with your computer by its name. Tap Pair this iPhone.

The address comes from the QR code, so there is nothing to type. - Or by hand: tap Enter a code, enter the address and port your computer shows under its code, type the six digit code, and tap Pair this device. On a phone that is already paired, the same screen is Connection, in Settings from the sidebar.

Settings, then Connection. 
Address, port and code, then Pair this device. - That is it: You’re connected, your agents are on the phone, and your computer lists it.


Your other workspaces
New in Bloks 3, with the iPhone app 3.0. The phone pairs with the workspace whose code it read, Personal for most people. Your other workspaces on the same computer are listed under it in the phone’s workspace switcher: tap one to add it, with nothing to scan. Only workspaces of your own are offered, each where its phone access is on, and Bloks on your computer tells you each time a phone adds one. A workspace can still be paired the long way, from its own Settings, Phone and devices.
Away from home
Pairing works on your own wifi. Bloks Cloud carries the same connection from anywhere and buzzes the phone when an agent needs an answer. It buys reach and push, not hosting: your computer still runs the agents and still holds the keys.
If it does not connect
- Connection says Revoked on your computer. The phone was removed on the computer. Press Pair a phone there and scan the new code, or forget this pairing and type the code.
- That code stopped working early. A few wrong tries close a code. Press New code when you are ready.
- The phone cannot reach the computer. Check both are on the same wifi, not a guest network, which usually keeps devices apart, and that a VPN on either side is off. If the card says Restart Bloks to finish turning this on, press Restart now.
- Your computer’s firewall. If you declined the incoming connections prompt, allow Bloks in your firewall settings (on a Mac, System Settings, Network, Firewall).
- It worked yesterday and not today. New in Bloks 3. A Mac that rejoined the network at a new address, or a Bloks that started on another port because the usual one was taken, is found again by a paired iPhone by itself, and Connection says where. On Windows or Linux, enter the new address under Connection and tap Apply and reconnect.
After pairing
The sidebar holds Today, Chats, Automations, Memory, Usage, Activity and Watchers, in the order you choose with a long press. Today puts what waits on you first, then what is running, what is coming up, and the morning brief with Listen to hear it read aloud. Answers that come as cards, tables, charts and forms are drawn by the iPhone itself, to tap like the rest of the app. Home screen widgets show who needs you and who is working, with the agents’ real faces, and a running task shows live in the Dynamic Island.
Watch an agent work
New in the iPhone app 3.0. When an agent has a browser of its own or a cloud computer, the screen button at the top of its chat shows that screen live while it works. Open it full size to look closer, and take over: a tap clicks that spot and what you type goes where the cursor is, for the moments only you can get past, like a sign‑in or a code sent to your phone. An agent working on your Mac’s own screen can be watched from the phone, never worked from it.
Where you are, if you choose
New in the iPhone app 3.0, and off unless you turn it on. In the phone’s Settings, Location, Share my location tells one workspace of your own, on your own computer, the city you are in, and the neighbourhood when iOS gives Bloks a precise fix, with how long ago it was. Exact position adds where you are to within a few metres, and Share while Bloks is closed lets a watcher act when you arrive somewhere, for “when I land, send me the hotel address”, without a running track. Your own agents hear it while it is recent. Only the last place is kept, never a history, and never in a backup. Pause sharing keeps it from agents and watchers; turning it off, or Forget in Settings, Phone and devices on your computer, drops it. People you invite never get it.
On the lock screen
New in Bloks 2. When an agent needs you, the notification comes from the agent, with its face, and says what it wants: “Scout needs your approval: Bash: npm run deploy”. Those words are sealed on your computer for your phone alone and opened on the phone, so neither Apple nor Bloks Cloud can read them. Press and hold for Hold and Allow: Hold never lets anything through, and Allow asks for Face ID first. A risky ask offers Review in Bloks instead, so the whole command is read before it goes. iOS’s own Show Previews setting decides whether the words show while the phone is locked.
Send to Bloks, Siri and Shortcuts
New in Bloks 2. In any app’s share sheet, choose Bloks to send a link, a page or some text to an agent, with a line about what you want done with it. Or ask Siri: “Ask Scout in Bloks”. The same Ask an agent action is in the Shortcuts app and can go on the Action Button. It lands in that agent’s conversation on your computer, without opening the app.
Brief, watchers and notes on the phone
New in the iPhone app 2.1, with Bloks 2.3 on your Mac. Today carries the morning brief, with Listen to hear it read aloud; Watchers, in the sidebar, pauses one or looks now; and About you keeps or dismisses what your agents suggest. The brief’s notification opens it directly, and “What’s my brief in Bloks” asks Siri for the headline.
On Apple Watch
Bloks comes to your watch with the iPhone app: who is working, what is waiting on you, and the brief’s headline, in complications and a Smart Stack card that lead with who needs you. An approval can be answered from the wrist, with the agent’s face: Hold or Allow goes through your iPhone to your Mac, the same way the lock screen buttons do. Questions that need words stay on the phone.
Use Bloks in a browser
New in Bloks 2. A server running bloks-server 1.11 or later already makes links that open here.
With Bloks Cloud, the app you use on your computer also opens in any browser, on a work laptop or a friend’s machine, at bloks.dev/web. Your agents keep running on your own computer; the browser reaches them the way your phone does.
- On your computer, open Bloks and go to Settings, Phone and devices. Press Pair a phone, or Pair another phone once one is paired, and under the code press Pair with a link.
- Bloks makes a link that works once, for fifteen minutes, through Bloks Cloud. Copy the one under Open in a browser and open it in the browser you want to use. The one under it, Paste into the Bloks app or another computer, is the same pairing for an app.
- Name the browser and choose Connect this browser.

- That is it. The same app, the same agents, the same approvals and undo.

- Sealed in the browser. Every request is sealed on your side for your computer alone and opened only there. bloks.dev serves the page and never sees what it carries. The browser keeps two keys that cannot be copied out of it, and not the pairing itself.
- Only browsers you trust. A connected browser can do everything your Bloks can, like your phone. Do not connect a shared or public computer.
- Leaving. Press Disconnect this browser in Settings, Phone and devices in the browser, and remove it from the list on your computer, which ends it everywhere at once.
- What stays on the computer. A few things need the computer in front of you: pairing new devices, choosing folders, and a live terminal.
Running Bloks on a server? bloks-server pair prints a link, and its page offers Use it in this browser.
Always on: Bloks on a server
Bloks runs on your computer, so when it sleeps your agents stop. To keep them working, run Bloks on a computer that never sleeps: a small rented Linux server, a Mac mini, a home server. Your laptop, your phone and the people you share rooms with then use that one Bloks through Bloks Cloud. It needs Bloks Cloud, and nothing else.
- Download bloks-server from the latest release onto that computer and unpack it. It needs Node 22.6 or newer. A Dockerfile and a systemd unit are inside if you prefer those.
- Start it with
node bin/bloks-server.mjsand keep it running (Docker, systemd, tmux, whatever the machine already uses). It listens on the machine itself only and opens no port. - In a second shell on that computer, turn on Cloud with
node bin/bloks-server.mjs activate blok_live_..., using your licence key. - Run
node bin/bloks-server.mjs pair. It prints a link that works once, for fifteen minutes. - On your laptop, open Bloks, go to Settings, Phone and devices, Where your Bloks runs, paste the link and choose Use that Bloks. The app restarts connected to your server: the same app, your agents living on the server.
Agents run on the engines installed on the server. Install and sign in to Claude Code or Codex there, or give your agents API keys from the app. To go back to the Bloks on your laptop, choose Use this Mac instead (Use this PC instead on Windows) in the same place; nothing on either computer is deleted.
One Bloks per computer’s data. New in Bloks 2.5.22. Two Bloks servers sharing one computer’s data would overwrite each other’s work, so only one may use it at a time. If bloks‑server is already running on a Mac and you open the Bloks app on that same Mac, the app says so and shows the server’s address, instead of starting a second one. Stop the server first if you would rather use the app there.
If you stay on a laptop, Bloks keeps it from dozing off while an agent is working, and if it does sleep in the middle of a task, the agent picks up where it left off when you are back. Rather not keep a machine running yourself? That is what managed hosting will be.
Managed hosting
New. Hosting Standard and the two Bloks Hosted bundles are on sale now; Hosting Lite is coming soon. Prices are on the pricing page.
Hosting puts your agents on a private machine of their own that we run for you: a whole Linux machine with 2 vCPU, 4 GB of memory and 10 GB of disk, never shared with anyone. They keep working while your Mac is asleep, closed or off, and the Mac becomes one more window onto them, beside your phone and a browser.
- Two kinds of machine. Hosting Lite sleeps when it is idle and wakes, usually in seconds, for a message, a routine or a watcher. Hosting Standard is always on: live Telegram and Slack, several agents working at once, the agent browser, and a desktop you can watch and take over. Both add onto Bloks Cloud or Bloks Team, and the Bloks Hosted bundles include Standard.
- How you reach it. Your phone and any browser (see Use Bloks in a browser) reach it through Bloks Cloud, with the connection sealed end to end. The Bloks app on your Mac opens it like any other workspace.
- Moving in. When you buy Hosting, Bloks moves your workspace over for you once the machine is ready, with progress you can see. Your agents, memory, rooms, routines, watchers, workflows and conversations move. Keys and secrets never travel, so Bloks lists the ones to enter again, unless your plan includes Bloks AI. The copy on your Mac stays, marked as moved, and its routines, watchers and bots stop there, so nothing runs twice.
- Moving back. You can move a hosted workspace back to this Mac at any time. It is your choice, never automatic, and it does not change your plan.
- Models. Your agents think with Bloks AI, which the Hosted bundles include, with your own Claude Code or Codex sign‑in on the machine, or with API keys. Claude Code always runs on your own Claude plan or key. A personal plan is priced for one person’s ordinary use, so agents working around the clock on one are between you and its maker.
- What it cannot do. The machine is not your Mac: it cannot reach the files, apps or screen on your own Mac, or a local model running there.
- Backups. Write the whole hosted workspace out to one file from Settings, Backups, at any time. Automatic nightly backups are coming.
Usage and spending limits
New in Bloks 3.
Usage, on the main rail, shows what your agents used: over 7, 30 or 90 days or this month, as cost, tokens or turns, for every agent and engine or one of each. A headline compares it with the span before, a chart draws it by day with a line per engine, and the breakdown by agent, engine or day narrows the whole page when you click a row.

- Only real prices, or honest estimates. A cost is an engine’s own price when it reports one. Most APIs report tokens and no price, so Bloks estimates those turns from the providers’ list prices, refreshed daily, and writes them with a
~. A model nobody has a price for says Not reported, never a made‑up figure. Bloks AI is shown as a share of your allowance, never in dollars. - Limits. Below the numbers, what each plan, allowance and key has left: a Claude or ChatGPT plan as its engine said on its last turn, Bloks AI’s month and day, and your spending limits.
- Spending limits. Press Set limit on any engine that runs on an API key of yours and give it a monthly line. At the line, new turns on that engine pause, or go to the agent’s backup engine, until you raise it or the month turns; a turn already running finishes. For a host of your own, or a model the list does not have, give your own price per million tokens and the limit counts by that.
- A notice before you run out. When a plan window, Bloks AI or a spending limit is getting close, the message box says Approaching limit or Limit reached and when it resets. View usage opens Usage on that agent; dismissing one keeps it away until it has something new to say. The iPhone app shows the same notice.


In a workspace with members, what each person starts is booked to them: members see their own usage and limit, and you and your admins see everyone’s.
Your plan
New in Bloks 3.
Settings, Plan is your membership, as bloks.dev has it, and the same in every workspace on the computer: one plan and one key cover them all. Bloks itself is free with your own keys; without a key, the page says Self-hosted and shows what a plan would add. Already bought one? Under Have a Bloks key from bloks.dev?, press Enter your key and paste the one from your confirmation email.

- Your plan. Its status (active and when it renews, past due with a way to update your card, or when it ends), how you are billed, and since when. Manage billing opens your billing on bloks.dev in your browser.
- What you have. What it includes and how much is in use: workspaces online, members, a shared room and Bloks AI, where they apply.
- Your key. Shown masked, to copy, replace, or remove from this computer. One key covers every workspace on the computer, and it never leaves it except to bloks.dev.
- Your options. Where the plan can go next. Each opens bloks.dev in your browser with your key already in place, and when you come back, the page looks again and everything the plan opens is on at once. Hosting is listed as coming soon, and cannot be bought yet.
If bloks.dev cannot be reached, the page shows what it last said, and when. A bloks://plan link opens it straight from anywhere.
Your data
One folder per workspace: ~/.bloks for Personal, and a folder of its own for each of the others. Agents, conversations, memory, keys, settings, artifacts. Back it up and you have backed up that workspace; move it to a new Mac and its agents come with you; delete it and Bloks has genuinely forgotten it. Settings, Backups can also write a whole workspace out to one file, keys left behind, for an empty workspace on another computer to take in. Keys are stored with owner‑only file permissions and are never echoed back to any screen once saved. The full story is on the privacy page.
When something goes wrong. New in Bloks 3. A window whose page stops loads again by itself; after three times in a minute it says so, with a Reload button, and a part of the window that fails to draw shows a calm panel instead of an empty window. The app keeps a small log of its own (on a Mac, in ~/Library/Logs/bloks), and a crash leaves its report in your computer’s own crash folder. Neither is sent anywhere. For a bug report, Settings, About and updates, Copy diagnostics puts versions, connection states and which keys are set, never the keys themselves, on your clipboard to paste.