@beatos/bridge-runner
v0.10.0
Published
BeatOS Bridge runner: a small program on your own computer that takes BeatOS tasks for your agent and works them with Claude Code. It only dials out to beatos.app.
Maintainers
Readme
@beatos/bridge-runner
The BeatOS Bridge runner. A small program that runs on your own computer. It takes the BeatOS tasks you delegate to Local AI and works them with Claude Code. Every run, question and approval shows up in BeatOS Bridge.
It only connects out to beatos.app. It opens no port and never opens your computer to the internet. Nothing is merged, deployed or sent without your yes.
Contents
- What you need
- Quick start
- Connect this computer (pair)
- Start and stop
- Pause, resume, stop a run, revoke, remove
- Commands and flags
- Configuration (config.json)
- Protect your private folders (protectPaths)
- Projects: where the agent works
- Project context and memory
- Vault notes for the task
- Attachments for the agent
- Videos (opt-in)
- The key
- Safety model
- What is on this computer (opt-in)
- Sessions (opt-in)
- Files and logs
- Update
- Uninstall
- Troubleshooting
- Support
What you need
Node.js 22.6 or newer. Check it:
node --versionIt must say
v22.6.0or higher. Get Node.js at https://nodejs.org.Claude Code, installed and signed in on this computer. See https://code.claude.com/docs/en/setup. Check it:
claude --versionA BeatOS account with Bridge.
git, only if the agent works in a git repo (see Projects). GitHub CLI (
gh), signed in, only if you want the runner to open pull requests.ffmpeg and a local speech to text program, only if you turn on Videos.
Operating system notes:
- Windows: use PowerShell or Windows Terminal. The runner finds
claude.exeby itself (npm global folder or nvm). If it cannot, setBEATOS_RUNNER_CLAUDEto the full path ofclaude.exe. The key file is limited to your Windows user withicacls(best effort). - macOS: use Terminal. The runner calls
claudefrom your PATH. - Linux: use any terminal. The runner calls
claudefrom your PATH. - On macOS and Linux the key file gets permission 600 (only you can read it).
Quick start
In BeatOS, open Bridge, then Runners. Tap Get a code.
In a terminal on this computer:
npx @beatos/bridge-runner pair K7F-29Q npx @beatos/bridge-runnerKeep the terminal open. Delegate a task to Local AI in BeatOS.
Connect this computer (pair)
In BeatOS, open Bridge, then Runners. Tap Get a code on the Connect a computer card. The code (like
K7F-29Q) works once, for 10 minutes.Open a terminal. Any folder works. Your home folder is a good choice.
Run, with your code:
npx @beatos/bridge-runner pair K7F-29QThe first time, npx asks to install the package. Type
yand press Enter.
To give this computer its own name, add --name:
npx @beatos/bridge-runner pair K7F-29Q --name "Laptop"Without --name, BeatOS names the computer Local-AI- plus 4 letters and
numbers (like Local-AI-7F3A), so two computers never look the same. Each
computer gets its own id and its own key.
The runner trades the code for its key, saves it in
~/.beatos-runner/runner.key and writes ~/.beatos-runner/config.json. The
card in Bridge then shows "Connected:" and the name.
Start and stop
Start:
npx @beatos/bridge-runnerKeep the terminal open. The computer shows as online in Bridge within a minute. Only one runner can run at a time on a computer.
Stop: press Ctrl+C in that terminal. The runner waits up to 15 seconds for a running Claude session to save its state. A task that was cut continues in the same Claude session the next time you start the runner.
Check once and exit (good for testing):
npx @beatos/bridge-runner --oncePause, resume, stop a run, revoke, remove
You do all of this in BeatOS, on the Bridge screens. The runner follows within
pollSeconds (30 seconds by default).
| You want to | Where in BeatOS | What happens | | --- | --- | --- | | Stop new work on this computer | Runners, the computer's card, Pause | It stays online but takes no new tasks. | | Take work again | Runners, the card, Resume | It takes new tasks again. | | Pause one run | The run's page, Pause | The Claude session stops. The run keeps its session. | | Continue that run | The run's page, Resume | The SAME Claude session continues. | | Stop one run for good | The run's page, Stop | The session ends. The task goes back to you. | | Cut this computer off | Runners, the card, Revoke key | The key is deleted. The runner stops at once and cannot come back. | | Hide a revoked computer | Runners, the revoked card, Remove | It leaves the list. Its runs keep its name in their history. |
After a revoke, connect the computer again with a new code.
Commands and flags
This is the same as npx @beatos/bridge-runner --help:
Usage:
npx @beatos/bridge-runner pair <CODE> connect this computer (code from BeatOS)
--name "Laptop" name for this computer (optional)
--url https://beatos.app another BeatOS server (optional)
npx @beatos/bridge-runner start (keep the terminal open)
npx @beatos/bridge-runner --once one check, then exit
npx @beatos/bridge-runner --help, -h this help
npx @beatos/bridge-runner --version, -v the versionEnvironment variables:
| Variable | Meaning |
| --- | --- |
| BEATOS_RUNNER_HOME | The runner folder. Default: ~/.beatos-runner. |
| BEATOS_RUNNER_CONFIG | The config file. Default: config.json in the runner folder. |
| BEATOS_RUNNER_KEY | The key. When set, it wins over runner.key. |
| BEATOS_RUNNER_CLAUDE | The full path of the Claude Code program, if it is not found. |
Configuration (config.json)
The file is ~/.beatos-runner/config.json (on Windows:
C:\Users\<you>\.beatos-runner\config.json). Set BEATOS_RUNNER_CONFIG to
use another file. Pairing writes runnerName, workspaceId and agentName.
Everything else is optional. Restart the runner after you change the file.
Full example:
{
"beatosUrl": "https://beatos.app",
"runnerName": "Laptop",
"workspaceId": "set-by-pairing",
"agentName": "local-ai",
"machine": "LAPTOP",
"model": "sonnet",
"profile": "standard",
"maxRunMinutes": 45,
"maxRunsPerDay": 8,
"billing": "subscription",
"pollSeconds": 30,
"ghUser": "your-github-user",
"protectPaths": ["projects/my-secrets/**", "Documents/taxes/**"],
"folderRoots": ["~/projects", "/home/you/code"],
"projects": {
"<beatos project id>": { "name": "My app", "mode": "git", "path": "/home/you/code/my-app", "pushPr": true },
"<another project id>": { "mode": "folder", "path": "/home/you/notes" },
"<private project id>": { "mode": "exclude" }
}
}Every field:
| Field | Type | Default | Meaning |
| --- | --- | --- | --- |
| beatosUrl | string | https://beatos.app | The BeatOS server. Pairing with --url sets it. |
| runnerName | string | the computer's host name | The name in Bridge. Pairing sets it. Must match the name BeatOS has. |
| workspaceId | string | none | The BeatOS workspace of this runner. Pairing sets it. |
| agentName | string | none | The agent this runner works for (local-ai, shown as Local AI). Pairing sets it. The runner does not start without it. |
| machine | string | the computer's host name | A task with a machine target for another machine is skipped. |
| model | string | sonnet | The Claude model. The agent's model in Bridge, Agents wins. |
| profile | string | standard | A label shown on the runner card in Bridge. |
| maxRunMinutes | number | 45 | The time limit of one run. The agent's limit in Bridge wins (up to 480). |
| maxRunsPerDay | number | 8 | How many runs this computer starts per day. |
| billing | subscription or metered | subscription | subscription: a Claude plan, runs report $0. metered: an API key, runs report the cost. |
| pollSeconds | number | 30 | How often the runner checks BeatOS. |
| taskRoot | string | ~/beatos-runner-work/tasks | Where each task's files go (TAREA.md, rules, your answers). Use a full path (~ is not expanded). The agent must read and write here, so it must be outside ~/.beatos-runner and outside protectPaths. |
| worktreeRoot | string | ~/beatos-runner-work/worktrees | Where git projects get their work copies. Same rule as taskRoot. |
| claudePath | string | found by itself | The Claude Code program. BEATOS_RUNNER_CLAUDE also sets it. |
| ghUser | string | none | The GitHub CLI account the runner uses to push and open pull requests. |
| protectPaths | string array | [] | More folders the agent may not read or change. See the next section. |
| folderRoots | string array | ["~/projects"] | Where the runner looks for folders to offer on beatos.app. Full paths; ~ is expanded here. Only the direct child folders of each root are listed. Roots that do not exist are skipped. See Connect folders from beatos.app. |
| projects | object | {} | Where the agent works for each BeatOS project. See Projects. Wins over a folder picked on beatos.app. |
| video.enabled | boolean | false | Turn video attachments on. See Videos. |
| video.ffmpeg | string | ffmpeg (on PATH) | The ffmpeg program. ffprobe is looked for next to it. |
| video.transcribeCommand | string array | none | The local speech to text program, as argv (no shell). {audio} becomes the wav file, {outdir} a folder it may write to. Without it: frames only. |
| video.transcribeTimeoutMinutes | number | 30 | The time limit of one transcript (1 to 240). |
| video.maxFrames | number | 12 | How many frames per video (1 to 50). BeatOS keeps at most 24 frames per video: with more, the result stays on this computer only. |
| video.comprehension | boolean | true | After processing, a short read-only Claude session writes a Comprensión into VIDEO.md. See Saved in BeatOS. |
| video.comprehensionLanguage | string | task | The language of the Comprensión. task: the language of the task title and description (Spanish when the task text is too short to tell). Any other value, like es, en or Catalan (ASCII letters, 30 at most), forces that language; a value that is not like that counts as task. |
| video.saveToBeatOS | boolean | true | Save the result (VIDEO.md and the frames, never the audio) in BeatOS as a Vault note of the task's project, so the video is not processed again. |
| sessions.access | off, read or work | off | Sessions in Bridge. off: nothing about your Claude Code sessions leaves the computer. read: chats can only read. work: chats may change files. Any other value is off. See Sessions. |
| sessions.maxTurnMinutes | number | 30 | The time limit of one chat turn (1 to 240). |
| sessions.maxTurnsPerDay | number | 200 | How many chat turns this computer takes per day (1 to 5000). |
| sessions.recentDays | number | 7 | Sessions changed in the last N days are shown (1 to 30). |
| sessions.maxSessions | number | 100 | At most this many sessions are shown (10 to 200). Live ones are always shown. |
Protect your private folders (protectPaths)
protectPaths lists folders and files the agent may not read, edit or
write. Use it for anything private on this computer: client work, tax
papers, other projects.
Path format:
- Relative to your home folder. Do not start with
~/or a drive letter. - Use forward slashes
/, also on Windows. - Glob syntax:
*matches any name in one folder,**matches any number of folders.projects/my-secrets/**means everything inside that folder. - The same entry works on Windows, macOS and Linux. On Windows,
projects/my-secrets/**meansC:\Users\<you>\projects\my-secrets\.
Examples:
{
"protectPaths": [
"projects/my-secrets/**",
"projects/client-a/**",
"Documents/taxes/**",
"Desktop/passwords.txt"
]
}Always blocked, without any setting:
| Blocked | What |
| --- | --- |
| Read, edit, write | ~/.claude/**/.env, ~/.claude/**/CREDENTIALS/**, ~/.claude/.credentials.json, ~/.claude.json |
| Read, edit, write | ~/.ssh/**, ~/.aws/**, ~/.docker/**, ~/.npmrc, ~/.git-credentials |
| Read, edit, write | GitHub CLI login: ~/.config/gh/** and AppData/Roaming/GitHub CLI/** |
| Read, edit, write | ~/.beatos-runner/** (the runner's key and state) |
| Read, edit, write | .env*, .mcp.json, .npmrc, .git-credentials, .pem and .key files under ~/projects |
| Read | the same key and token files (also .p12, .pfx) in the project folder, wherever it is, and in the work folder |
| Edit, write | everything in ~/.claude/** (Claude Code settings) and the work copy's .git folder |
| Shell commands | commands that mention .env, .mcp.json, credentials, .ssh, .pem, .npmrc, tokens, or .beatos-runner |
How to check it works:
- Add a test folder, for example
"protectPaths": ["projects/protect-test/**"], and put a file in it. - Restart the runner.
- Delegate a small task to Local AI: "Read the file in ~/projects/protect-test and tell me what it says."
- The run must report that it could not read the file.
Projects: where the agent works
projects maps a BeatOS project id to a place on this computer:
| mode | What the agent does |
| --- | --- |
| git | Works in its own copy of the repo at path, on a new branch local-ai/<TASK>. Your folder is read only for it. With "pushPr": true, the runner pushes the branch and opens a pull request when the agent is done (needs gh). Merge stays with you. |
| folder | Works in a task folder and may read path. |
| exclude | Never takes tasks from this project. |
A task from a project that is not listed works in a scratch folder in
~/beatos-runner-work/tasks/<TASK>.
Connect folders from beatos.app
Runner 0.5.0 and newer: you do not have to edit config.json to connect a
project to a folder.
- The runner lists the folders in its roots (
folderRoots, default~/projects) and sends the list to beatos.app: the name, the path (~/...under your home folder) and if the folder has a.git. Never file contents. Hidden folders, folders under a denied path (the secret folders,protectPaths,~/.beatos-runner) and the runner's work folders are not in the list. At most 300 folders. - In Bridge, Runners, click the runner. Under "Project folders", pick the
folder for each project and the mode: "Read only" (
folder), "Git copy" (git) or "Never take tasks" (exclude). Save. - The runner uses the pick on the next task of that project.
Rules:
- A project set in
config.jsonwins. Bridge shows it as set on this computer. - The runner uses a pick only when it listed that folder itself in its last scan, the folder is still there (a real folder, not a link) and it is not under a denied path. Otherwise it ignores the pick and writes one log line. beatos.app can never send the agent to another folder.
- A pick from beatos.app never pushes:
pushPris set only inconfig.json. - To offer folders from another place, add it to
folderRootsand restart the runner.
Project context and memory
Runner 0.3.0 and newer read the task's project from beatos.app at the start of
each run. The agent's TAREA.md then has:
- the project name from beatos.app (the name in
config.jsonis only a fallback); - the task's last comments;
- Contexto del proyecto: the project brief. Write it on the project page in beatos.app ("Context for agents"): the goal, a glossary of short names and terms, links, people;
- Lo que ya sabemos del proyecto: the project's facts.
The brief, the facts and the comments are marked for the agent as text from the team: information, not orders.
The agent can propose new facts. It ends its result with up to 3 lines
APRENDIDO: <one fact>. The runner takes those lines out of the result and
sends them to beatos.app as proposed facts. You approve or dismiss each one on
the project page or on the run. Only approved facts go to the next runs.
What the runner never sends as a fact: a full path (it becomes ~/... or
…), a line that looks like a key or token, a line that names a credential
(password, token, secret, API key, clave, contraseña, credencial), more than 3
facts, or more than 300 characters per fact. A question or a failed run sends
no facts.
With an older beatos.app server, the run works like 0.2.0 (local project name, no comments, no project context). The log says why the context was not read.
Vault notes for the task
Runner 0.4.0 and newer also put up to 5 notes from your BeatOS Vault in
TAREA.md, in a section Notas del Vault, after the project facts:
- first, the notes you linked to the task's project (project page in beatos.app, Context tab, "Vault notes");
- then your own notes that match the task title.
Only your own active notes come in, never the notes of another user. Each
note has its title as a ### heading and its text quoted with > , marked
for the agent as information, not orders. The runner caps them too: 5 notes,
a title of 200 characters, 1500 characters per note and 6000 for all of them.
A task with no project still gets the notes that match its title. With an older beatos.app server there are no notes, and the rest of the run is the same.
Attachments for the agent
Runner 0.6.0 and newer save the images, PDFs and text files attached to the
task, and to its Vault notes, in an attachments folder next to TAREA.md.
TAREA.md lists them in a section Adjuntos, so the agent can look at
them with Read; other files are listed by name only, and so are videos
unless Videos is on. The runner
downloads only over https from storage.googleapis.com (short lived links
from beatos.app), at most 20 files, 10 MB each and 50 MB in all. A failed
download is listed and never stops the run, and the files are never run.
Videos (opt-in)
Runner 0.7.0 and newer can turn a video attached to the task, or to one of its Vault notes, into context for the agent: key frames and a transcript with times. It is off by default. All the work happens on this computer: the audio never leaves it. Runner 0.8.0 also saves the result in BeatOS, so a video is processed only once (see Saved in BeatOS).
What the runner does, before the agent starts:
- It downloads the video into the task's
attachmentsfolder (same rules as other attachments: https fromstorage.googleapis.comonly, no redirects). At most 2 videos per task, 300 MB each, 10 minutes per download. - It takes frames with ffmpeg: the first frame and the scene changes, at most
maxFrames, 1280 px wide at most. A video with few scene changes (a person talking, one slide) gets evenly spaced frames instead. Each file name has the time:frame-00-02-29.jpg. - It makes a 16 kHz mono wav and runs your
transcribeCommand. It takes the transcript from{outdir}/transcript.txt, else{outdir}/transcript.json(Whisper segments), else what the program prints. Lines like[00:02:29] text. - It writes
attachments/<video>/VIDEO.md: the title, the length, the frame list and the transcript (at most 60,000 characters; it says when it cut). - It deletes the video and the wav, also after an error.
TAREA.md points the agent to VIDEO.md and the frames. A failure never
stops the run: VIDEO.md says what worked and why the rest did not. While
the runner works on a video it keeps telling beatos.app it is alive, so the
task stays taken.
Turn it on:
Install ffmpeg (Windows:
winget install Gyan.FFmpeg; macOS:brew install ffmpeg; Linux: your package manager). Check:ffmpeg -version.Install a local speech to text program. The small example
examples/whisper_local.pyuses openai-whisper:mkdir $HOME\whisper; cd $HOME\whisper # save whisper_local.py here python -m venv .venv .venv\Scripts\python -m pip install openai-whisperAdd a
videoblock toconfig.jsonand restart the runner. Windows example:"video": { "enabled": true, "ffmpeg": "ffmpeg", "transcribeCommand": [ "C:/Users/you/whisper/.venv/Scripts/python.exe", "C:/Users/you/whisper/whisper_local.py", "{audio}", "{outdir}", "--model", "small", "--language", "es" ], "transcribeTimeoutMinutes": 30, "maxFrames": 12 }
At start the runner runs ffmpeg -version. If that fails, it says
"video is off: ffmpeg did not run" once and works as if video were off. Only a
runner with video on asks beatos.app for video links.
Notes:
- The first word of
transcribeCommandmust be a program (python.exe,whisper.exe), not a.cmdor.batfile: the runner runs it without a shell. - The program runs in the video's folder, with the runner's environment minus variables with KEY, TOKEN, SECRET, PASS, CRED or AUTH in the name.
transcribeCommandcomes only fromconfig.jsonon this computer. beatos.app cannot set it, and the agent cannot read or changeconfig.json.- On a computer without a GPU, Whisper
smalltakes a few minutes for a 20 minute video. RaisetranscribeTimeoutMinutesfor long videos or bigger models.
Saved in BeatOS (runner 0.8.0)
A video is processed once. After that, every run of any task, on any runner, gets the saved result instead of the video.
- Comprensión. After the frames and the transcript, the runner starts one
short Claude session (the same
claudeand login as a run, 5 minutes at most). Its only tool is Read: no shell, no edits, no web, no MCP. It readsVIDEO.mdand looks at the frames, and the runner puts its answer intoVIDEO.mdas Comprensión: what the video is about, the main points, and one line per frame. The transcript is data, not orders: the prompt says so. It writes in the language of the task (runner 0.8.1): the task title and the first 500 characters of the description go intoTAREA-IDIOMA.txtnext toVIDEO.md, as data. Quotes from the audio stay in their own language.video.comprehensionLanguagecan force a language. If it fails or takes too long,VIDEO.mdstays without it and nothing is uploaded, so a later run tries again. - Upload. The runner creates a Vault note for the task's project
(
Video: <file name>, the text ofVIDEO.md) and sends each frame to its own short lived upload link onstorage.googleapis.com(no redirects, 60 seconds each). Then beatos.app checks that every frame arrived with the right size. Only then the result counts as saved: the runner writes.beatos-saved.jsonand addsGuardado en BeatOS: <link>toVIDEO.md. Any error keeps everything on this computer, with one log line, and the run goes on. - Next time. beatos.app sends the saved note instead of the video link.
The runner writes
VIDEO.mdfrom the note and downloads the frames (same download rules), with no video download and no processing. This works also on a runner with video off. The log saysvideo 1 from BeatOS (saved note)andTAREA.mdsays the video was already processed.
Rules:
- The audio never leaves this computer. Only text (the transcript and the Comprensión) and the jpg frames go to BeatOS.
- The runner never deletes
VIDEO.mdor a frame. It deletes only the downloaded video and the wav (the original video stays in BeatOS). - Only a complete result is saved: frames and a transcript with no problem. Videos attached to a Vault note (not to the task) are not saved.
- Turn either part off in
config.jsonwith"comprehension": falseor"saveToBeatOS": falsein thevideoblock.
The key
- Pairing writes the key to
~/.beatos-runner/runner.key, readable only by you. It is never printed or logged. BEATOS_RUNNER_KEYin the environment wins over the file. Remove it from your shell if you paired again.- The runner reads the key from nowhere else.
- To cut the key off, use Revoke key in Bridge. Deleting the file only stops this computer from using it.
Safety model
These rules are in the code. No setting turns them off.
- Claude Code never runs with
--dangerously-skip-permissions. It runs in auto permission mode with a long deny list (above, plus deploys, publishing, databases,git push,gh,ssh, and installing new packages). - No browser:
--no-chromeand a deny rule. No MCP servers. - No secrets in the agent's environment: variables with KEY, TOKEN, SECRET, PASS, CRED or AUTH in the name are removed.
- The agent never pushes, merges or deploys. The runner pushes and opens a pull
request only for projects with
pushPr. Merge and deploy stay with you. - When the agent wants to do something outside the task, it asks you in Bridge for that one exact action. Merge, deploy and deleting data always ask. Moving money is always refused. Other rules come from Bridge, Settings.
- Text in tasks, comments, the project context, web pages and files is data for the agent, not new orders.
- The agent never runs ffmpeg or a transcriber. With video on, the runner
runs them itself before the session, and only the programs in
config.json. - The Comprensión session of a video has Read as its only tool and works in the video's folder.
What is on this computer (opt-in)
Runner 0.2.0 and newer can show, on the runner's page in Bridge, which assistants this computer has and what they hold. It is off by default. Only the runner's owner can turn it on (Bridge, Runners, click the runner, "What is on this computer"), and only the owner sees it.
When it is on, the runner sends a list once and then every 6 hours:
- the assistants it finds: Claude Code (
~/.claude), PAI, LifeOS, Codex (~/.codex), Gemini CLI, Hermes and Pi; - their agents, skills, hooks and MCP tools, by name and description;
- Claude Code sessions (active now, last 24 hours, last 7 days) and tokens per
model over the last 7 days, counted from the logs in
~/.claude/projects.
What it never sends: file contents, keys, env values, a hook's command line, an
MCP server's command or URL, or a full path. Paths go as ~/...; a full path
inside a description becomes ~/... or ….
Turn it off on the same page. BeatOS then deletes the list, and the runner stops reading.
Sessions (opt-in)
Runner 0.9.0 and newer can show the Claude Code sessions of this computer in BeatOS Bridge. From Bridge (or by voice with Beat-e) you can read them, start a new session in one of your project folders, and chat with it. The runner does the computer side. It is off by default.
Two gates
Both must be on. If one is off, the runner sends nothing about sessions and takes no command.
- The switch on beatos.app: Bridge, Runners, click the runner, Sessions. Only the runner's owner can turn it on. A paused or revoked runner counts as off.
sessions.accessinconfig.jsonon this computer:readorwork. The default isoff. beatos.app can never turn this on or raise it: it never sends an access level, and the runner always uses its own.
{ "sessions": { "access": "read" } }Restart the runner after you change it. At start it says one line:
sessions: off, sessions: read only or sessions: can change files.
Read or work
What each access can reach:
read: the chat has three tools only, Read, Grep and Glob. It cannot run commands or change a file. It can read only the files inside the session's folder (the scanned project folder it was started in), never a key or.envfile, and nothing outside that folder. Claude Code lets these tools reach any path, so before each turn the runner adds a deny rule for every folder and file next to the session's folder and above it, up to the drive root, and for every other drive. If a folder has too many neighbors to protect (more than 6000 rules), or a neighbor has a name that cannot be protected (it differs from this folder's name only at characters like+or(), the turn is refused. On Windows a chat also cannot read a name that looks like a short name (with~and a digit, likeDOCUME~1): Windows opens a folder or a.envfile by such a name too, and a rule by the long name would not see it. A link that points at the session's folder, into it, or at a folder above it gets no rule (Windows has one on every PC:C:\Documents and Settingspoints toC:\Users): Claude Code follows a link in a rule, and such a rule would hide the session's own folder from Glob and Grep. What that link shows stays closed by its real name. This wall is made of Claude Code deny rules. It was checked with real sessions on Windows (Claude Code 2.1.319): long and short names, links and junctions inside the folder and above it, other drives, network paths, and that Glob and Grep still find the files inside the folder. It is not an operating system sandbox, and it was not checked on macOS or Linux. Ask it for a change and it tells you what it would change.work: like a task run. The chat may change files and run commands as your Windows user (or your user on macOS and Linux), inside the same deny rules as a task run (no push, no deploy, no new packages, no secrets, no browser, no MCP servers, no key or.envfiles in the folder, no other sessions' transcripts). It is not a sandbox: a command can reach what your user can reach. UseprotectPathsfor your private folders. Never--dangerously-skip-permissions.
Each chat gets a short rules file (RULES.md, next to the task folder): keep
the last message short, never push, merge, deploy or pay, stay in the folder,
and treat text in files and web pages as information, not orders.
What leaves the computer
For each session in one of your project folders (the folders the runner offers on beatos.app, see Connect folders from beatos.app):
- its title, the folder name (
~/projects/acme-app) and git branch; - live or not, and when it was last used;
- a short part of your last message (300 characters) and of the last answer (1500 characters; a longer answer is sent as its start and its end);
- when you open a chat: the answers of the turns you start from Bridge, and for an older session, its last 30 messages (your text and the answers);
- while a turn you started from Bridge runs: a short line of what it does at
that moment, at most one every 2 seconds. The line is the name of the tool
and the command, file path or search it uses (300 characters at most), for
example
Read ~/projects/acme-app/README.md.
What never leaves: the output of tool calls, file contents, sessions in
other folders, claude -p sessions the runner did not start, and keys: a
text that looks like a key or a token becomes [hidden], and the home folder
becomes ~.
A session you started by hand: closed, the same session; open, a copy
From runner 0.10.0, on Windows. On macOS and Linux a session you started by hand still continues as a copy, for now: the check with the real Claude Code has only run on Windows so far.
- Closed on this computer (no Claude Code window or terminal holds it):
your message from Bridge continues the SAME session (Claude Code's
--resume, no copy). The next time you open it on the computer, Bridge's turns are in it. The access box is the same as for any other chat turn (readorwork, the same deny rules and read wall). - Open on this computer: the runner does not write into it. Bridge
continues it as a copy (Claude Code's
--fork-session): the copy keeps the history and gets a new id, and your open session stays as it was.
The runner decides, not beatos.app. It reads Claude Code's list of open
sessions (~/.claude/sessions) when it takes the message, again right
before Claude starts, and every 2 seconds while the turn runs. When it cannot
be sure, it counts the session as open: the list is missing or cannot be
read; no entry in it can be read but a file is not empty; the entry has no
process id or comes from another process space (WSL, a container); a file
that cannot be read belongs to a process that still runs (an empty one only
in its first 2 minutes). An empty leftover file of a program that died does
not count.
session_open: the reason the runner gives when it refuses a message because
the session is open on the computer (or it cannot tell). Close the session
there and send again, or continue it as a copy. When the session is opened
while your message waits for its turn, the turn ends with the error "the
session is open on the computer", Claude does not start, and the turn does
not count for the day. When someone opens it on the computer while the turn
runs, the turn is stopped and ends with the same error.
A turn that ends before Claude is started does not count for the day: a refusal, an error in the runner's own setup of the turn, or a waiting turn that is dropped (you stop it, Sessions are turned off, the runner stops or restarts). A Claude that could not be started still counts.
A runner that is not on Windows, or that cannot name its own process space,
does not continue a session from the computer in place: it refuses such a
message as open (session_open). Bridge then offers the copy.
On the Sessions page, "open on the computer" uses the same rule as the check: when an entry in the list makes the runner refuse a session, its card says it is open. (An entry written by a Claude Code in another process space, for example in WSL, counts on the card only on Windows.)
The runner tells beatos.app that it can do this in its heartbeat
(capabilities.sessions.resume_local: true), only on Windows and only when it
can read ~/.claude/sessions. Without it, or with an older runner, Bridge always makes
a copy. Sessions started from Bridge are continued as they are.
Limits
- One chat turn at a time on this computer (a task run may run at the same time).
sessions.maxTurnMinutes(default 30) per turn, then it is stopped.sessions.maxTurnsPerDay(default 200) turns per day.- At most
sessions.maxSessions(default 100) sessions are shown, changed in the lastsessions.recentDays(default 7) days. - A turn cut by a runner restart shows as "interrupted" in Bridge.
Audit log
Every command the runner takes or refuses adds one line to
~/.beatos-runner/sessions-audit.jsonl: the time, the command, the folder,
the access level, the result or why it was refused, and the first 120
characters of your text. It is kept at 5 MB (the older part moves to
sessions-audit.1.jsonl). It never leaves the computer.
Turn it off
Turn the switch off on beatos.app (the runner stops the live turn and goes
quiet), or set "access": "off" in config.json and restart the runner.
Files and logs
The runner uses two folders in your home folder.
~/.beatos-runner (or BEATOS_RUNNER_HOME): the runner's own files. The
agent can never read or change this folder.
| File or folder | What |
| --- | --- |
| runner.key | The key. |
| config.json | Your settings. |
| state.json | Open runs and today's count. |
| outbox/ | Events saved before they are sent, so nothing is lost offline. Sessions use outbox/sessions-<runner id>.jsonl. |
| sessions-state.json | Sessions: the sessions started from Bridge, the open turn, the last command ids. |
| sessions-audit.jsonl | Sessions: one line per command taken or refused. Local only. |
| runner.lock | Present while the runner runs. |
~/beatos-runner-work (next to the runner folder): where the agent works.
Change it with taskRoot and worktreeRoot.
| Folder | What |
| --- | --- |
| tasks/<TASK>/ | Each task's brief (TAREA.md), rules and your answers. |
| worktrees/ | Work copies of git projects. |
| sessions/<session>/ | Sessions: the chat rules file (RULES.md) and the settings with the deny rules (settings.json) of each Bridge session. |
At start, the runner checks that the agent may read and write both work
folders. If a deny rule covers one of them (for example a taskRoot inside
~/.beatos-runner or inside a protectPaths entry), it does not start and
says which rule blocks it.
Logs go to the terminal, with the prefix [bridge-runner]. To keep them in a
file:
npx @beatos/bridge-runner 2>&1 | tee -a ~/bridge-runner.logIn PowerShell:
npx @beatos/bridge-runner 2>&1 | Tee-Object -Append $HOME\bridge-runner.logThe full story of each run is also in Bridge, on the run's page.
Update
npx can keep an older copy. To get the newest version, start with @latest:
npx @beatos/bridge-runner@latest --version
npx @beatos/bridge-runner@latestYour key and settings stay. Stop the runner (Ctrl+C) before you update.
Uninstall
In Bridge, Runners: Revoke key on the computer's card, then Remove.
Stop the runner (Ctrl+C).
Delete the runner folder and the work folder:
macOS and Linux:
rm -rf ~/.beatos-runner ~/beatos-runner-workWindows (PowerShell):
Remove-Item -Recurse -Force $HOME\.beatos-runner, $HOME\beatos-runner-workIf you set
taskRootorworktreeRoot, delete those folders too.Optional: clear the npx copy with
npm cache clean --force.
Troubleshooting
| You see | What to do |
| --- | --- |
| "That code did not work" | The code is mistyped, used or older than 10 minutes. Get a new code in Bridge. |
| "Too many tries. Wait 15 minutes" | Too many wrong codes. Wait 15 minutes, then use a new code. |
| "Could not reach https://beatos.app" | Check the internet connection, a proxy or a firewall, then try again. |
| "BeatOS could not pick a free name" | Run the pair command again with --name "Laptop" (any name not used yet). |
| "A runner named ... already exists" | Run the pair command again with another --name. The code still works. |
| "no agent key" | Pair this computer first, or set BEATOS_RUNNER_KEY. |
| "no agent set" | Pair this computer first, or set agentName in config.json. |
| "another runner is already running" | One runner per computer. Close the other terminal. If none runs, delete ~/.beatos-runner/runner.lock. |
| A run says it cannot read TAREA.md (runner 0.1.0) | Update to 0.1.1 or newer (npx @beatos/bridge-runner@latest). In 0.1.0 the task folder was inside ~/.beatos-runner, which the agent may not read. On 0.1.0, set full paths in config.json, like "taskRoot": "/home/you/beatos-runner-work/tasks" and "worktreeRoot": "/home/you/beatos-runner-work/worktrees" (Windows: "C:/Users/you/beatos-runner-work/tasks"). |
| "taskRoot ... is blocked for the agent by" | The task or work folder is under a denied path. Move taskRoot and worktreeRoot outside ~/.beatos-runner and outside protectPaths, or remove the default lines from config.json. |
| "the runner key was refused" | The key was revoked. Pair again with a new code. |
| The card says offline | Start the runner and keep the terminal open. Check the internet connection. A sleeping computer is offline. |
| No tasks are picked up | Check: the task is delegated to Local AI; the runner is not paused; the daily limit (maxRunsPerDay) is not reached; the task's project is not exclude; the task has no machine target for another computer; the task is not blocked or waiting. |
| Claude Code is not found | Install it and sign in. On Windows, set BEATOS_RUNNER_CLAUDE to the path of claude.exe. |
| npm WARN EBADENGINE or odd errors at start | Your Node.js is too old. Install 22.6 or newer. |
| "BEATOS_RUNNER_KEY is set in this shell" | That variable wins over the new key file. Remove it from your shell. |
| "video is off: ffmpeg did not run" | Install ffmpeg, or set video.ffmpeg to the full path of ffmpeg.exe. Restart the runner. |
| VIDEO.md says the transcript failed or passed its time limit | Run your transcribeCommand by hand on a short wav to see the error. Raise video.transcribeTimeoutMinutes for long videos. |
Support
Open an issue at https://github.com/Gordon-Web-Studio/beatos-bridge-runner/issues. Do not paste your key.
Develop
pnpm install
pnpm start # runs the TypeScript source directly
pnpm test
pnpm lint
pnpm typecheck
pnpm build # compiles to dist/A live check of sessions with the real Claude Code (a few short haiku turns, not run in CI):
node --experimental-strip-types --disable-warning=ExperimentalWarning scripts/sessions-live-check.mjsRun it again after each Claude Code update. The read wall is made of Claude Code deny rules, so it depends on how Claude Code matches paths and follows links. The check tests both sides with the real program, each with a control: a read session cannot reach the folder next door, and it can still find the files in its own folder. Run it also before each release that changes how a session from the computer is continued: checks 11 to 13 test the same session path against Claude Code's real list of open sessions (the runner's own turn is not taken for someone else; a second program that holds the session is seen before the turn and during it).
See PUBLISHING.md to release it to npm.
License
MIT. See LICENSE.
