Bloks runs AI agents that can read your files, use your logged-in accounts, and drive a computer. That makes a few things worth stating plainly.
Open a private security advisory on the repository, or email the maintainer. Please don't file a public issue for anything exploitable.
Everything is local. Agents, transcripts, configuration and skills
live on your machine, in the workspace's own folder: ~/.bloks for
Personal, and a folder of its own in the app's data folder for every
other workspace. Bloks has no backend that holds your data, and nothing
you write is uploaded anywhere by us.
Bloks itself makes a few requests, none carrying your conversations: a
packaged build asks GitHub for the latest release on launch; npm is
asked whether an installed engine CLI has a newer release; browsing the
skill catalog fetches https://bloks.dev/skills/index.json, held for
half an hour (point it elsewhere with BLOKS_SKILLS_URL), and the team
gallery comes from bloks.dev the same way; the Catalogue of teams and
skills reads catalog/index.json from this repository's main branch on
GitHub (point it elsewhere in its settings, or with BLOKS_CATALOG_URL)
and the files it lists, kept on disk for offline, and a link you choose
to install from is fetched once, over https only; while an engine runs on a key
of your own, OpenRouter's public model list is fetched at most once a
day, with no key and nothing about you, to estimate what unpriced turns
cost; and with a Bloks key, bloks.dev is asked, with that key, about your
plan. Everything else on the wire is the engines (Claude Code, Codex and
the rest), the voice vendors whose keys you save (the text being read
aloud, to ElevenLabs, OpenAI, Fish Audio or xAI; and what you say on a
call or in meeting notes, as sound, a stretch at a time, to whichever
of ElevenLabs or OpenAI hears for you, unless a Whisper server of your
own or the Mac's on-device recognizer does), and whatever connectors
you configure, talking to their own services (with an app watcher on,
that includes a WebSocket to the realtime service Composio delivers
events through), and Bloks Cloud when you turn it on, which carries
sealed traffic it cannot read. A Chatterbox server for voices must be on
this computer or its local network (a loopback, private or link-local
address, or a local name): Bloks refuses an address on the internet,
since every reply read aloud is sent there as text with no key. A
Whisper server for hearing has the same rule, for the same reason: what
you say goes there as sound with no key. Recorded speech is held in
memory for the one request that turns it into text and is never written
to disk or logged; the page sends it to the workspace and never holds a
vendor key, and an agent's token cannot use that route. On a Mac
with phone access on, the desktop app
also says on the local network where each listening workspace is (see
Phones and other devices).
The harness server is loopback-only and origin-checked. Each
workspace runs its own, Personal on 127.0.0.1:8799 and the others on
ports of their own, and none listens on your network unless you turn on
phone access for that workspace. But loopback alone is not a boundary. A browser will
happily send cross-origin requests to it from any page you visit, and a
CORS "simple" request skips preflight entirely. So every request is
checked: the Origin must be absent or loopback, and the Host must
name the loopback interface, which defeats DNS rebinding. A request
that carries a proxy's forwarding header (Forwarded,
X-Forwarded-For, X-Real-IP, CF-Connecting-IP and the like) is
never taken as local either, even from loopback: a reverse proxy or
tunnel on the same machine connects from there for somebody on the
internet, and NGINX by default rewrites Host to 127.0.0.1. See
server/http-guard.ts. On a bloks-server that is still not enough:
a proxy that adds no forwarding header, or a plain TCP tunnel, can
deliver anybody to loopback with any Host and Origin. There the
owner's own commands also carry a key the server makes at each start,
in local.key in its data folder, readable only by the account it
runs as (server/local-key.ts), and a request without it is a device
like any other.
A local service's wake is labelled, not trusted as you. A program on
this computer can wake one agent in one exact private conversation
(POST /api/bots/:id/wakes, server/service-wakes.ts). Only a direct
loopback request with a loopback Host and no Origin or Authorization
header (and on a bloks-server, the owner's key above) is accepted, never a browser page, a phone, the relay or an
agent's credential: no more than any local program could already do
through the owner's API. Its words are kept as a local service's, which
nobody can edit, and the agent is told they are that service's request,
never your own words or your approval.
Secrets sit in a plaintext file. Each workspace's config.json
(~/.bloks/config.json for Personal) holds any API keys you paste,
and the header values you give a custom endpoint, which are handled as
keys: never sent back to a window, left out of backups and settings
inspections, and taken out of any error that quotes one. It is
written 0600 inside a 0700 directory. That keeps
other user accounts out, but it is not encrypted at rest. Moving these
into the macOS Keychain is the top open item.
An engine's added accounts sign in on this computer, into folders of
their own. A second Claude Code or Codex account is signed in with the
engine's own login, in Terminal, into a folder under the workspace's data
folder (engine-accounts/, 0700). The engine writes its credential
there or in the macOS Keychain; Bloks never reads, copies, logs or sends
it, and only points a turn's CLI at the folder. Only the person's setup
(settings, instructions, skills, plugins) is linked in from the main
sign-in's folder, never its credential or its sessions. The folders are
left out of backups and workspace moves, and are never used for a turn
that works in a container or on another machine. Only a window on this
computer can add, sign in or remove an account; the owner's paired
devices can see them and choose the one in use; an agent's token and a
member get nothing. Removing one runs the engine's own sign-out, then
deletes the folder.
Which program runs as an engine is the person's choice, on this computer. An engine's CLI can be started from a path other than PATH's copy. Only a window on this computer can set it (never a phone, a remote window or an agent's token), the path must be a file that can run, the Cursor editor is refused where the Cursor CLI is meant, and every change is written to the activity ledger.
Bringing a setup over copies a key only when you tick it. Bring
your setup reads Claude Code's, Codex's, Cursor's, OpenClaw's, Hermes'
and OpenBot's files under your home folder, read only, by name, and never
opens a file named like a credential (auth.json, .credentials.json,
.env, tokens, keys, OpenClaw's credentials folder). The one database
it opens is OpenBot's, read only, for one table of agent settings; its
chat history, vault and saved logins are never read. An OpenBot transfer
file you pick is sent to the workspace's computer and judged whole before
anything in it is read: a path that is absolute or climbs out, a link,
an encrypted entry or one past the size limits refuses the whole file,
which is then not kept. Files it brings into an agent's workspace are
regular files only, never over one already there, and never one named
like a credential. An MCP server's
environment and headers, and a chat app's token, arrive as names with
empty values. Each value is typed in by you, or copied from the other
tool's config because you ticked the box for that one value; a value is
never sent to the window, never put in the record of what was imported
or in what an undo keeps, and lands only where you would have typed it
(config.json). A chat app's token is checked with that app and saved
switched off. Rules an import makes are only ever as broad as the
original when they allow, and an agent's own tool limits become denies
for that agent alone. The routes answer only the owner, never an agent's
credential or a member, and every import can be undone.
Approvals are the safety gate. When a provider asks to do something
risky, Bloks surfaces an approval card and blocks until you answer.
Don't route around it. Engines reach Bloks over protocols that can carry
a permission request (Claude Code and Codex natively, Gemini CLI over
the Agent Client Protocol) precisely so this gate exists; a headless
"approve everything" mode is not used.
The one card an agent's credential may close is its own question asked
without waiting (Codex's async question), which nothing is held on:
bloks unask withdraws it, from that agent's own turn, with nothing
answered for you. Approvals, questions it waits on, workflow gates and
another agent's questions are refused, and an answer you gave first
stands.
An agent's browser and computer go only where its settings and its engine both allow. Its own browser, with any sign-ins you borrowed into it, and its computer reach an agent as tools on Claude Code, on Codex and on the ACP agents that take MCP servers (Devin, OpenCode, Gemini CLI, Cursor, Grok CLI, Command Code), only on a turn you asked for or set up, never on an email from anyone or a shared room member's turn unless you opened them to that room. Codex never has them on a turn that is not yours, whatever the room allows. Claude Code and Codex call them without asking on your own turns, as Claude Code always has; an ACP agent asks as its own permission rules say, and its questions reach you as cards. The cloud box's key travels to the computer server in its environment (for Codex, in the thread's config over its standard input), never in a command line, and is taken out of the copy of each turn's frames Bloks keeps. An agent working in a container or over SSH reaches them through the workplace gate with its turn's token; they run on this computer and nothing of it is run there. An engine that cannot be handed them is given neither and told so.
Scripts are the owner, and ask like the owner. bloks-server run,
team apply and chat (docs/SCRIPTING.md) speak
as the person, so their routes (/api/runs, /api/teams/apply) answer
only this computer and the owner's own paired devices, never an agent's
credential or a member's device, and the commands refuse to run inside
an agent's turn. On another computer they take a paired device's token
from the environment or a file, never from the command line. None of
them answers an approval or a question on its own: a run that meets one
stops and says so, and the card waits in the app. Applying a team file
never deletes or archives anything and never touches an agent's engine,
keys or approvals.
A turn's command line is narrower than you. An agent's turn gets a
credential of its own that lasts the turn, works only on this computer,
and reaches only the routes listed in server/agent-cli.ts; each change
it makes counts against twelve a turn, and agents writing to agents are
held at the limit you set in Settings, Behaviour. Opening a new
conversation is on that list only as saying its first message, to the
agent itself or one it may already message, and is refused wherever that
message would be. An empty conversation, and which one you have open,
stay yours.
An agent writes only into conversations it is part of. An agent's
words arrive as a conversation's next turn and are answered with that
conversation's context, so knowing a conversation's id is not enough to
write there. An agent's credential may name one of the agent's own
conversations, the recipient's first one (where its words go without a
name anyway), one it opened with bloks tab, or one it is already in
exchange with, either way round; anything else is refused with that
rule before a word is written, the kept-back last message included. A
member's private conversation is never named by an agent, its own
included, and the routes an agent uses on its own conversations (a
component, a shared file, a new title) keep to the same rule. Without a
name, a reply goes back to the conversation it answers and a new request
to the first one; which conversation you have open never decides it.
Take-back and stopping another agent name no conversation at all, and
your own messages go wherever you send them, as before.
An agent adds to your list, and only you close it. A routine's report
that finds something you have to do yourself goes on your list
(server/todos.ts) through bloks todo, which is only on the agent's
own full credential: never a member's or a member's own agent's, never
a turn a Telegram person or an unlisted mail started, never a shared
room's. An agent reads, refreshes and clears only lines it put there,
by its own keys (/api/bots/:me/todos); the list as you see it and
marking a line done or dismissed are yours (/api/todos is on the
agents' never list, and a member's credential never reaches it). A line
is plain text, a title and a detail with lengths capped, shown with the
agent's name and a link to the conversation it came from; it runs
nothing and opens nothing but that conversation. What an agent read can
still steer what it writes there, as it can steer its answer, so treat
a line as the agent's words. The morning notification says only how
many things wait, never what they are.
An agent can point at a setting, and propose a few, never change one.
bloks where reads the app's own Settings index and bloks open puts a
button in the conversation that opens a page; neither changes anything.
bloks settings propose puts a card in front of you for one of a short
list of everyday preferences (PROPOSABLE in
server/settings-proposals.ts): Behaviour's recall, nightly tidy,
summarise as you go, other changed files and skill suggestions; the
morning brief's switch, time, notifications and sections; the proposing
agent's own notifications, effort and model on the engine it already
has; and the effort new agents start on. Nothing changes until you tap
Change, which only you can (/api/settings-proposals is on the agents'
never list, and a member's credential is refused), and the change is
the Settings page's own request, made as you and recorded as yours. An
agent never proposes approvals or rules, keys, secrets or sign-ins,
engines, members, invites or roles, phone access or pairing, remote
access or Bloks Cloud, the plan, billing or spending limits, the limit
on agents writing to agents or the task budget, backups or restore,
moving or exporting a workspace, deleting anything, the browser's sites,
Home Assistant, or anything about security: each is refused by name
with the page to send you to, and test/agent-guide.test.ts holds that.
An agent cannot speed its watchers past the usual six turns an hour. A watcher
is a way for an agent to wake itself, so each starts at most so many
turns an hour (perHour, server/watchers.ts). You set 1 to 30 on the
watcher's page. Through an agent's credential the limit is at most the
usual six (agentPerHourCeiling), so it can put back a limit it lowered
but never pass six; a higher limit you set stays until it lowers it, and
anything more is kept to that and the agent is told so. A finding
past the limit waits for the next turn allowed rather than being dropped.
The renderer is pinned to its own origin. The packaged app serves its
UI with a strict Content-Security-Policy: no remote script, no remote
frames, no form posts, and connect-src 'self'. The Electron window runs
with context isolation on and Node integration off, denies every
permission request except the two the app actually uses, refuses to
attach a <webview>, and hands any external link to your real browser
instead of navigating the app frame.
Input is bounded. Every field that reaches disk or a system prompt is
length-capped (server/limits.ts), oversized request bodies get the
socket closed rather than buffered, and an over-long message is refused
rather than silently truncated.
Analytics are off unless you build them in, and blind when on. There
is no analytics token in this repository. If you set VITE_POSTHOG_TOKEN
for your own build, autocapture, session recording and performance
capture are all disabled and text is masked, so only the named counters
in src/lib/analytics.ts are ever sent. No message content, agent name
or file path is included in any event.
What a crash leaves stays here. A native crash in any of Bloks'
processes leaves a minidump in this computer's crash folder, and the
crash reporter runs with uploading off, so there is nowhere it is sent.
macOS still writes its own report. The desktop app also keeps a small log
of its window and processes, app.log in its logs folder (on a Mac,
~/Library/Logs/Bloks), moved aside at 512 KB, never in a workspace's
folder and never sent off this computer. What the page writes to it is
budgeted, so a page failing in a loop cannot fill the disk.
Signal is signal-cli's, not Bloks's. An agent on Signal answers on an account linked to signal-cli on this computer, which keeps the account's keys in its own data folder; Bloks stores the account's number, the owner's and who is let in, never a credential. signal-cli's daemon has no password, so Bloks only ever talks to one on loopback, and anyone on this computer who can reach that port can speak as the account: unlink it in Signal on the phone (Settings, Linked devices) to end it. On the owner's own account, signal-cli receives every conversation; Bloks reads only Note to Self and drops the rest unread, but signal-cli may keep attachments others send in its folder. A person let in without full access talks to an agent with no tools and nothing of the owner's, and everything their turn asks goes to the owner.
The home asks first. Home Assistant's token lives in config.json
with the other keys and never reaches a client or a turn. Agents see only
the entities the owner lists, and only agents the owner names, in the
owner's own conversations. Every change is a card unless the owner marked
that entity as one to change without asking, and locks, alarms and garage
doors always ask. A long-lived token acts as the Home Assistant user who
made it, so make it on an account that can reach only what agents should
be near. What devices report reaches an agent as data, cleaned and
bounded.
Your phone, a browser at bloks.dev/web or another computer of yours reaches a workspace as a paired device, with a bearer token of its own; the workspace keeps only its sha256. Pairing is the only way to become one, so it is kept narrow. A member's device comes in through an invite instead (see People in your workspaces).
- A code exists only when you ask for one. Phone access is off until somebody turns it on at the computer, and the workspace listens on the network only after Bloks restarts with it on. It listens on IPv4 and IPv6, and takes IPv6 connections only from local addresses (unique local, such as Tailscale's, and link-local): a global IPv6 address, often the open internet with nothing in front of it, is refused. A six digit code and its QR are made when somebody presses Pair a phone, and the routes that make or cancel one answer only on this computer and on your own paired devices, which are the only way in to a workspace on a server with no screen; never a member's device or an agent's credential. A code works once, lasts five minutes, and five wrong tries close it. It is held in memory, never on disk, and the window closes it when the panel showing it closes. A pairing link, for a device on another network, works once for fifteen minutes and is shown only in those same places. Switching phone access off and removing every device answer only on the computer, since from a device they would cut that device off too. The one other way a pairing is made is for a phone you already paired, below.
- A server reached your own way. A
bloks-serverlistens on loopback and is reached through Bloks Cloud unless its owner says otherwise where it runs (server/self-host.ts, docs/SELF_HOSTING.md):BLOKS_LISTEN=0.0.0.0to listen beyond loopback (in a container, behind its published port),BLOKS_PUBLIC_URLfor the address of their reverse proxy, tunnel or VPN that devices pair at, andBLOKS_CLOUD=offto send nothing to Bloks Cloud or bloks.dev. None of them can be set from a device, and none widens what a request gets: anything that is not the server's own loopback needs a paired device's token, and without one reaches/api/healthand the pairing claim alone. Its codes are the ones above, made only at the server or on a device of yours, and handed out with the address in a link thatbloks-server pairprints at the server. - Finding the computer again. On a Mac, while phone access is on and
the workspace listens on the network, the desktop app announces it on
the local network as
_bloks._tcp(server/announce.ts): the computer's name, the workspace's name unless it is Personal, the port, and a tag that is a hash of a random key in the workspace's folder. Nothing in it is secret, and nothing in it is trusted. Before a paired phone sends its token to a Bloks it found that way, it asksPOST /api/pair/provewith a nonce, and only a Bloks that holds that phone's pairing can answer with the right HMAC. The announcement ends with the server. - Another workspace from a paired phone. A phone you paired with one
workspace can ask it which other workspaces of yours are on the
computer, and for a pairing to one (
server/other-workspaces.ts). Only your own paired devices may ask: never a member's device, an agent's credential or the computer's own window. Only your own workspaces are listed, never one you joined, and a pairing is made only for one that is already online with Bloks Cloud or listening for phones, which only the computer can switch on. It is single use, lasts three minutes, and comes back over the channel the phone is already trusted on; a device may have five in ten minutes. The computer shows a notification each time one is made, whatever its notification settings, naming the phone and the workspace it asked from. - A terminal from a device. A terminal is a shell with the account
Bloks runs as, so on a computer running the desktop app it opens only
in that computer's own window, never from a paired device. A machine
nobody sits at is the exception, and only for its owner's own paired
devices (
server/deployment.ts): a managed hosting machine always, and abloks-serverof your own only whenBLOKS_OWNER_TERMINAL=1is set where it runs, which no device can switch on. Never a member's device, a device nobody paired, or an agent's credential. A refused device is told why. Through Bloks Cloud its live output is sealed for the one device that follows it. - Pictures of a screen. While an agent works, its browser or cloud computer is pictured for the window and your phone, and a person can click, type, scroll and press keys in them from the chat or the phone; an agent's credential cannot. The Mac's own screen shows everything open on it, so it is held tighter. It is pictured only while an agent's turn is driving the Mac and your phone asks, at most about once a second, by the desktop app, which needs Screen Recording already granted and never asks macOS for it. That picture never goes on the event stream, is refused to an agent's credential, and is not a route a member's device can call. A member's stream carries no screenshots at all, and nothing on a phone can click on the Mac.
Bloks has a browser beside the chat that agents drive and you watch
(server/browser-core.mjs, server/app-browser.ts). In the desktop app
it is the app's own (electron/app-browser.mjs); on a server with no app
behind it, the server keeps it, a headless Chrome
(server/server-browser.ts). It is signed in as you wherever you sign
in, which makes it worth guarding.
- Its own session, nothing of the app's. Each workspace browses in a
persistent session partition of its own (
persist:bloks-browser-<id>): its cookies and storage are never the app's, and never another workspace's. A tab is a sandboxedWebContentsViewwith no preload, so a page has nowindow.bloksand no bridge to anything. Every permission a page can ask for (camera, microphone, location, notifications, devices) is refused except fullscreen and writing to the clipboard. Deleting a workspace clears its browser's data, and Settings, Browser signs out of every site at once. - Only the web. A tab never goes to a
file:,chrome:,devtools:,javascript:ordata:address, or anything else that is not http or https, and never to a Bloks server on this computer, on any port a workspace or the app's own page uses, under any spelling of loopback. This is checked on every navigation and redirect, including the ones a page starts, and a page's requests to those ports are cancelled before they leave. - Who drives it. An agent reaches it only through its turn's own
credential (
/api/agent/browser), and only in a turn the owner started in the owner's own conversations: never a member's turn, a shared room's, an unlisted email's or a Telegram person's, because the browser is signed in as the owner. Its settings, its picture and the route another app uses (/api/browser) are never reachable with an agent's credential. Another AI app reaches it through the MCP server, from this computer only, and gets less than an agent: nothing it does can ask you, so whatever would ask is refused for it. A hosted workspace has no Bloks browser. - On a server of your own. With no desktop app behind it
(
bloks-server, the Docker image), the server runs the browser itself: a headless Chrome in a profile of the workspace's own (browser-sessionin its data folder), behind the same rules, the same commands and the same guard on every navigation, redirect and popup (Chrome's Fetch domain; every page starts paused until its guard is on). You see it as pictures and use it with input events (/api/browser/screen,/api/browser/input,/api/browser/do), which are the owner's alone, from any of your paired devices or a web door session: never a member's device, a guest, an agent's credential or another origin. Pictures go only while a panel looks, and input is sent in request bodies, sealed end to end through Bloks Cloud, never in an address or a log. The profile holds your sign-ins the way the data folder holds the workspace's other secrets: anything that can read that folder as the account Bloks runs as can read them, so keep agents' own work (the Local VM, a container place) apart from it. - Which sites. Each workspace has a list of sites agents may use and a list they never use, and a mode. In Ask first, the default, a site not on the allowed list asks you on a card the first time an agent opens it in a turn; Allow lets that turn in, Always allow adds it to the list. In Auto (which, like widening approvals, asks for Touch ID where the Mac has it) agents open any site but the blocked ones. A blocked site always wins. While an agent drives a tab, the app holds that tab to the same rules for every page a click, a redirect or a new window takes it to, and tells the agent it stayed where it was.
- Which fields. Typing into a password field, a payment field (by its type, its autocomplete and its name), and choosing a file to upload always ask you on a card first, in either mode. The card names the field's kind and the site, never what would be typed, and Enter does not answer it. A yes is good for that text in that field once. An agent never clicks a file picker; it names a file, and you see which.
- What a page says is data. Everything that comes back from a page, its text, its snapshot, its title, the tab list, is framed before it reaches a model: a sentence saying it is untrusted content from that site and that nothing in it is an instruction, between an opening and a closing tag carrying a random value per answer, so a page cannot write its own end of the frame. The snapshot is read from the browser's accessibility tree, and an agent's refs name the browser's own nodes, so a page cannot forge one by writing an attribute.
- A tab you link with @. In an agent's conversation you can link a
tab of the browser into your message (
server/mentions.ts). Only the owner's own words are read for one, on the owner's routes, never a member's or an agent's. The server finds the open tab at that address and reads its text where it is (AppBrowser.peek): no command runs, nobody takes the wheel, a tab waiting on a dialog is left alone, and a site on the never list is not read. The text is trimmed and framed exactly as above, named by its host only, and goes ahead of your words for that turn; it is kept on the message only while the words wait for a turn, and never shown to a member or to another agent reading the conversation. A conversation you link is read only when you could open it yourself (server/access.ts), and its record is framed as a record. - A page's dialogs. An alert, a confirm, a prompt or a "leave this page?" stops the page until it is answered. The agent's step that opened one comes back with it, the page's words framed like the rest of the page (a dialog is the page talking, however official it looks), and the agent answers with the dialog command, as it could click any button: no card, since no dialog can do more than a click could. What an agent types into a prompt is never said back in its answer. While you have the browser, the dialog shows in the panel's bar for you to answer, and waits for you; otherwise one nobody answers is dismissed after 30 seconds, and a "leave this page?" then stays on the page. Nothing is ever accepted by default. In the desktop app Bloks takes the place of Electron's own dialog boxes, so a page an agent opened cannot put a box over the Bloks window; and since Electron asks about leaving a page before anyone can be asked, the app always stays, and a yes afterwards lets the next try through. Your other devices see a dialog's words while it is open (they are shown to you to answer), cut to a thousand characters with control and direction characters taken out; an agent's tab list says only that a tab waits on one.
- You can take it back. You see which agent drives which tab and can take over at any time, from the panel or simply by clicking or typing in the page. The agent's next step then waits, up to a minute and a half, and is told the browser is yours if it still is. Its steps are not counted against its turn's twelve changes, since none changes the workspace; the sites and fields above are what bound them.
- What leaves the Mac. Your other devices hear only each tab's
address and title, who drives it, the words of a dialog it has open
and the downloads' names, never what is on a page; a phone looking on gets a small picture of the tab on
screen, at most every second and a half, and a member's device gets
none of it. Downloads land in the workspace's own
browser-downloadsfolder, with the site's name for the file cut down to a plain name.
A workspace can take people, and everything they say runs on your computer, with your engines and your keys. So the door and the rooms behind it are built to be narrow.
- Getting in takes more than the link. An invite works once, for a
day. Its code is never sent to a server (it sits after the
#in the link), guesses are rate limited, and a join password, when you set one, is checked only on your computer and closes the invite after five wrong tries. With Approve each person on, which is the default, nobody is in until you and they have read the same four words. Those words are bound to their device and to your workspace's join key, so a relay that swapped the key to read the request would show different words on the two screens. - The request travels sealed. Joining is sealed for your workspace's join key, so Bloks Cloud, which carries it, cannot read the name or the password in it. The joiner's device token never leaves their device; your computer keeps its sha256.
- A member's device reaches a named list and nothing else. Every
route a member may call is listed in
server/member-access.ts, and anything not listed is refused, so a new route is closed to members until somebody decides otherwise. They never reach your settings, your keys or your own conversations, and what crosses to them from the event stream is stripped of tool arguments, file paths, screenshots of your screen and the buttons on your approvals. - Their turns get none of your standing trust. A turn a member starts never runs in Full access, gets none of your saved secrets, and reaches your apps, tool servers or computers only where you opened them to a room. Approvals in a team conversation or a room go to whoever started the work, to you and to your admins; in a member's own private conversation or solo agent, they answer their own.
- Their spending is capped by you. Per member: a monthly limit on what your API keys cost, a share of Bloks AI, how many solo agents they may make and which engines those use.
- Their own agents are deleted, never read. You and your admins see
the agents members made for themselves by name and maker
(
/api/workspace/member-agents), and may delete one. Nothing of what was said to it crosses that route either way: deleting it deletes its conversations unread, and the record names who deleted it and whose it was. - Who changes an agent's settings. You change any agent's; an admin
any agent's but your own solo ones; a member only the agents they
made, and even there cannot let one act without asking past accepting
edits, give it a computer, or move it to an engine their limits leave
out (
mayChangeSettingsandsettingHeldinserver/access.ts, served by/api/workspace/agents/:id/settingsfor you and/api/member/agents/:id/settingsfor people you let in). The route refuses whatever the screen shows held, with the same reason, and never an agent's credential or a guest. An agent's settings carry nothing of its conversations: opening a member's agent is not reading it. - Private means private. A member's one to one with an agent is theirs. You can turn on reading members' private conversations for the workspace, and every member is told which way it is set. Past the transcript too: the agent keeps a memory of that member's own there and works in a folder of theirs, what it looks back on is only what that member could already read, and your own conversations, search and recall never reach a member's private words (only reading them, when you turn it on). On Claude Code a member's private turn may not read or change any agent's own folder or anybody else's, even with a yes.
- Each member's apps and keys are theirs. A member's own Composio
key and keys are kept apart from yours and from each other's
(
people/<id>/own.json, 0600), are never shown back to anybody, and are used only by a turn that member asked for in their own private conversation or solo agent: never a team conversation, a room, your turns or another member's. Who asked is the turn's own record, never a name in the words. Removing a member removes them. In that turn a request for a key or an app asks the member, never you, so nothing lands in your keys or signs in under your account. - Your accounts and your self are yours. A member's turn, and every turn of a member's own agent (even one you set going in a room you share), gets none of your apps, keys, profile or shared memory, and none of what the engine itself brings on your computer: on Claude Code the connectors of your claude.ai sign-in (Gmail, Calendar, Drive) are off, only the MCP servers Bloks names are loaded, and your CLAUDE.md and Claude's memory of you are not read; on Codex the MCP servers in your own Codex settings and the apps of your ChatGPT sign-in are switched off for that thread, and a Codex that will not take that does not answer anyone but you. The agent is told whose apps it has: the member's own in their private conversation or solo agent, and nobody's in a team conversation or a room, so it never says it is signed in to your mail. Other engines that run a program (Gemini CLI, Cursor, OpenCode and the rest) still load an MCP server set up in their own settings on your computer; keep anything signed in as you out of those, or limit which engines members may use. OpenCode can instead be given a setup of the workspace's own (Own setup for this workspace under it in Settings, Engines and keys), which leaves your own OpenCode settings, plugins and servers out of every turn there, yours included; the providers it starts with are the ones you had connected, copied once into the workspace's folder, which stays private to you and out of backups.
- A room's Auto reads the room as data. In a room set to Auto, a
message that names nobody is shown to a small model, with the members'
names, roles and briefs and the last few lines, so it can pick who
answers. Anybody in the room, a guest from a chat channel included, may
write words meant to steer it, so they go in as escaped JSON inside a
block marked as data, and the answer must be one JSON object naming ids
from the list it was given; anything else, or no answer in 2.5 seconds,
and the lead answers. It can only pick agents the sender could have
named in that room themselves (
mayAddressInRoominserver/access.ts). By default it uses an engine the room's agents already run on, so the room's words reach no provider they were not already going to; a different one is your choice in Settings. Only you can set a room to Auto: an agent's credential may not, since each message then costs a call on your engine.
Who sees what is decided in one file, server/access.ts, as plain
functions a test can walk. Workspaces never share a folder, so an agent
in one cannot read another's memory, and the safety floor keeps agents
out of every workspace's folder, not only their own's.
bloks-server can also answer browsers at an address of your own
(BLOKS_WEB_URL), signed in with an OpenID Connect provider you run or
use (server/web-door.ts, server/oidc.ts). It is off unless set, and
it is a listener of its own, so the loopback port keeps every rule
above.
- Nothing through it is the computer itself. A reverse proxy on the
same machine connects from loopback with whatever Host it sends, so
connections through the web door are marked, and
isLoopbackPeerrefuses them (server/http-guard.ts). An agent's credential, the loopback-only routes, pairing and the terminal are out of reach there. - One credential, one place. A session cookie, HttpOnly,
SameSite=Strict, Secure with the
__Host-prefix on https, is the only thing the door reads; an Authorization header is dropped, so a paired device's token does nothing there and a session does nothing anywhere else. A request that changes anything must carry the door's own Origin. Only the cookie's sha256 is kept (web-sign-in.json, 0600). - The sign in is the standard one, checked fully. The authorization
code flow with PKCE (S256), a state that must come back once to the
browser that started it, and a nonce. The ID token is believed only
when its signature checks out against the provider's published keys
(never the client secret, never
none), and its issuer, audience, expiry, not-before, issued-at and nonce are right. The verifier and the client secret never reach the browser. - Who somebody is, checked on every request. The owner is whoever
BLOKS_OIDC_OWNERnames, read again each time; a member is an identity linked to a person who is still in the workspace. Removing a member, or changing who the owner is, ends their sessions at once. The allow lists gate every sign in but the owner's, and making members on first sign in requires one, so a provider that knows everybody (Google) cannot make everybody a member. - An invite still needs you. Signing in to use an invite makes the same request any device makes, bound to that browser's session, and it waits for you and the same four words. Until then the session reaches nothing but its own request.
- Whoever controls the provider controls the door. That is what
single sign-on means: an account that can become yours at the
provider, or join the allowed groups, can sign in. Use
subor a verified address as the person claim, not a name people can change.
An agent can work in a Docker container or on another machine over SSH
instead of on this computer. Its engine runs there; its stdio is carried
back over docker exec -i or ssh -T. The boundary between the two
sides is drawn on purpose:
- Only the owner sets it, on this computer. The routes refuse an agent's token, a member, a paired device and any website. Bloks only ever stops or removes a container it made for that agent, which it knows by a label it put there; a container you run is only execed into.
- What crosses to the other side is the turn's own. Its token, which
lasts the turn; the agent's command line; the persona and the MCP
config it would read here; the files the person attached to the
message; and the secrets you saved for agents. All of it travels on the
engine's own stdin, ahead of the engine, never in an argument that
pson either machine could read. This computer's environment does not go, and nor does any engine key or workspace key: Composio's, the box token, anANTHROPIC_API_KEYorOPENAI_API_KEY. - Your engine sign-in stays here. Bloks never copies a sign-in to a container or a host on its own. The Test says when the engine there is not signed in, and offers to open Terminal signed in there, or to copy your sign-in file after a card that names the file at both ends and says that anyone who can use that machine can then use it as you. The copy happens only for the plan that card showed, and is recorded with the agent. A Claude Code sign-in kept in the macOS Keychain is not a file, and is never copied.
- The way back in is a gate, not the workspace. On this computer a
request with no credential is you, so the other side never reaches the
workspace's own server. It reaches a gate (
server/workplace-gate.ts) on a port of its own: over an SSH reverse tunnel bound to the far side's loopback, at Docker's host address, or with the container's network off over a line of Bloks' own throughdocker exec. The gate answers nothing but a running turn's token, passes the workspace only the headers the command line needs (no origin, no cookie, no relay mark), where the agent's usual rules apply, and closes when the turn ends. The tunnel's port on the far loopback can be reached by anyone on that machine, and they get nothing without the token. - MCP servers stay here. The approval bridge, the computer, the browser and your own servers run on this computer as before, and the engine there reaches each over HTTP through the gate. A server's key is added here, so it never leaves either.
- SSH is keys only. Bloks runs ssh with
BatchMode=yes: no password prompt, and a host key this computer does not know is a refusal to fix in Terminal, never a question answered for you. A host is a name from your SSH config oruser@host, and nothing that begins with a dash, which ssh would read as an option. - Network off means two hosts. A container made with its network off
reaches only Bloks and its engine's own service (
LINE_HOSTSinserver/workplace.ts), on 443, through a proxy Bloks answers. An engine whose hosts depend on how it is set up cannot be run that way. - What it does there is not undoable from here unless its folder is this computer's own, mounted into a container. The settings say so, and so is the agent told. What it saves to its outbox there is brought back as plain files under plain names, never a link.
A skill is markdown that gets injected into an agent's system prompt on every turn. That means installing one is closer to running a script than to saving a note: a hostile skill can instruct an agent to exfiltrate files, misuse a connected account, or quietly ignore your instructions.
Bloks therefore:
- shows the full body before anything is installed,
- never fetches and installs a skill on its own initiative,
- caps skill size, and confines skills to slugged filenames inside
~/.bloks/skillsso a crafted name cannot escape the directory, - never changes a skill on its own. When suggestions are on, a review of
a finished conversation can suggest a new skill or a change to one,
and an agent can ask for a change (
bloks skill revise, or an MCP client'spropose_skill_revision). Every one of those is staged with its reason and its diff, and only the person keeps it. A conversation can contain anything a web page, a file or an email put into it, and a skill is read into every future turn, so letting a review or an agent rewrite one unattended would give whoever wrote that page a lasting say in what your agents do. The review is told that what it reads is data, and what it writes has anything shaped like a key taken out, but the guarantee is the person's approval, not the prompt, - keeps every version of a skill, with who made it and why, so a change that got through can be seen and put back. An agent's credential can read versions and ask for a change against the version it read; it cannot edit, restore, install, or keep a suggestion, and a change written against a version that has since moved on is refused rather than allowed to undo the newer one,
- lets an agent ask for a new skill (
bloks skill create) only as a request: the whole skill, files included, waits on a card in the conversation that shows all of it, and nothing is in the library until the person presses Add, through a route an agent's credential cannot reach and a member is refused. Whatever the agent says the person asked for, its words are an input, so the press is the approval. A request never writes over a skill already there, built-in or the person's, and Add is refused if the id was taken while the card waited, - keeps a skill's supporting files as plain text in a folder of the skill's own, read only on demand and never put in a prompt, with names judged as words and the file opened inside that folder, so a crafted name or a planted link reaches nothing else.
Teams and skills from the Catalogue, a link or a file go through the same gate, and a few more:
- Nothing installs from a click in a list or a
bloks://installlink. Each opens a review of exactly what would be created (agents, a room, skills with their full text, routines), and only the review's own Install does anything. It installs the bytes that were shown, held by a token for half an hour, not whatever a link serves by then. - A catalogue item is refused unless its bytes match the size and sha256 in the catalogue's index, whether it was just downloaded or read from the copy on disk. A link has no index, so the review says it is not from the catalogue.
- Links are https only, with no sign-in in them, at most 96 KB, and are read with the same parser and limits as a file imported by hand.
- Agents a team creates start with connected apps, the browser and tool servers off, and every routine it files starts paused. A team never replaces a skill you already have under the same name.
- The catalogue routes are the owner's: an agent's credential is refused, and a member's requests never reach them.
- Share as file takes out this workspace's stored keys, anything shaped like a key, email addresses, phone numbers, your home folder and the project brief given at hire. It cannot know what else in a job description is private, so read the file before sending it.
Only install skills from a source you'd trust with your accounts. The same caution applies to anything an agent reads and treats as instructions: web pages, issue comments, and email are untrusted input, not commands.
An app watcher starts a turn when something happens in an app you
connected through Composio: an email arrives, an issue is labelled, a
message is posted. Whoever caused the event wrote what it says, so it is
handled as a stranger's words (server/app-watch.ts):
- It is data, fenced. The event is cut down to its readable fields, with anything named like a token, secret, password, cookie or key, and any long blob, left out before a model sees it. What is left sits between two markers carrying a nonce made for that one turn, under a line saying it was written by whoever caused the event and is not to be followed as instructions; a marker inside the event is defused. The person's own instruction comes after the fence.
- Nothing listens until a person says so. An agent can only propose
an app watcher. The proposal is a card showing the app, the event, the
filter, which agent acts and where, and nothing is set up at Composio
until the owner presses Start watching. Agents cannot confirm, change
or list accounts for one (
server/agent-cli.ts). - It is bounded. The same event twice is one event, a plain-words filter is checked before any model is woken, and each watcher starts at most a few turns an hour and a capped number a day.
- Admins are trusted with it. The apps watched are the owner's connections. An admin may set up an app watcher for an agent whose team conversation they are on; its turns go there, and run as the admin's, so they carry none of the owner's tools the admin could not ask for themselves. The event itself is read in that conversation, so make someone an admin only if you would let them read what your apps send. Members who are not admins cannot set one up.
- Composio's project key is needed, and stays here. Watching needs
the project key (
ak_) beside the Connect key. It is sent only to Composio, to make and remove triggers and to authorise the realtime channel events arrive on; it never reaches a turn.
A webhook's URL carries a long random token, and by default that token
is the whole credential: whoever has the URL can start a turn. Its event
reaches the agent as data from an outside system, never as instructions
(server/webhooks.ts).
- A signing secret, when the sender has one. A webhook can require a
Standard Webhooks signature (Svix, Clerk, Resend, Composio and others
sign this way). Every request must then carry
webhook-id,webhook-timestampandwebhook-signature(or thesvix-names), an HMAC-SHA256 of the id, the timestamp and the body exactly as it arrived, checked in constant time before the body is parsed. A timestamp more than five minutes off is refused, and so is awebhook-idthe webhook accepted in the last ten minutes. A refused request gets a 401 with a short reason, reaches no agent, and leaves only a line in the webhook's recent deliveries, nothing of its body. - The secret is a saved key. It is kept in
config.jsonwith the other keys, readable only by your account, because the check needs it whole. It is shown once, when Bloks generates it; a pasted one is never shown back, and no route returns either afterwards. It is left out of an unsealed backup and named in a move, and a signed webhook that arrives somewhere without its secret refuses every request until one is set again, rather than taking the URL alone. - Only you set it. The webhook routes are the owner's. Members, admins and agents' credentials are refused, so no agent can set, remove or read a secret.
- What it does not cover. Seen ids are held in memory, so a restart forgets them; a captured request's timestamp keeps that to ten minutes at most, five either side of now. A webhook without a secret is exactly as before.
Export for training (Settings, Data, and bloks-server export-runs)
writes every conversation it is pointed at into one file, which is the
point of it and also why it is held close (server/run-export.ts):
- The owner's, on this computer. The routes answer Bloks on this
computer alone: never an agent's credential, never a member, never a
paired phone or a remote window. The command refuses to run inside an
agent's turn (a shell with
BLOKS_TOKENset). Nothing is sent anywhere; the file is written beside the data folder and shown, downloaded or deleted only by its own name. - Keys are always taken out. Anything shaped like a key, token or password, and every value this workspace has saved as one, is removed before a result is shortened, so a key is never cut in two and left half recognisable. Email addresses, phone numbers, home folder paths and the names of the people the workspace knows (members, guests, people on Telegram and Signal, the owner) go too unless you keep them. The scrubber matches shapes and known values: a secret with neither, typed into a conversation in plain words, can survive it. Read the preview before you share a file.
- Other people's words stay out. A member's words, a Telegram stranger's, a person's on Signal, mail and chat apps, and members' private conversations are left out unless you turn them on, and turning either on asks first. Private conversations are not even counted unless reading them is on in Members.
The macOS builds are signed and notarized. Everything on the
Releases page is built by CI from a tag. The macOS .dmg and .zip are
signed with a Developer ID certificate and notarized by Apple, so they
open without a Gatekeeper warning and can be revoked if a build is ever
found to be compromised.
The Windows and Linux builds carry no signature. SmartScreen warns on first run, and Linux does not expect one. If that matters to you, build from source. See docs/RELEASING.md.
-
The Bloks browser tells a payment field from its type, autocomplete and name, which a page can leave off. A card form drawn in a frame from another site, the usual way payment providers do it, never appears in an agent's snapshot at all, so you fill those yourself; a card field a page draws itself and names nothing is not caught. And a page can still show an agent anything: the frame says it is data, but a model can be talked into things.
-
Secrets are not in the Keychain. The desktop app keeps your Bloks key there, but each workspace's API keys are still in its
config.json. -
There is no sandbox between an agent and the rest of your machine beyond what the provider CLI enforces, unless you set it to work in a container (see Agents that work somewhere else). That includes agents a member of your workspace talks to: give a team agent only the folder and the tools you would let those people near. A member's turn on an engine with a shell (in their private conversation, a team conversation or their own agent) can, with their own yes, run a command that reads what your account can, the keys saved in your workspace's
config.jsonand other members' files on this computer included, which the file rules do not stop. Bloks keeps your accounts out of what it hands their turns; it cannot keep a shell running as you from your files. Where members should be kept apart from each other as well as from you, give their agents an API engine or Bloks AI, whose only tools are Bloks' own, or a container. And whoever runs the computer can read everything kept on it; every member is told so when they join.