@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,420 @@
1
+ # MCP servers
2
+
3
+ pi has MCP built in; pine decides which agent gets which server. Tools appear to the model as
4
+ `mcp__<server>__<tool>`. Characters such as `-` in a server's name become `_` there: the server
5
+ `home-link` offers `mcp__home_link__status`. Use the tool-name form in `approve`
6
+ patterns; the server's own `taints` and `approve` settings apply either way.
7
+
8
+ ## Global and per agent
9
+
10
+ Global servers go in `pine.json`:
11
+
12
+ ```json
13
+ "mcp": {
14
+ "web": { "pine": "web", "agents": ["scout"] },
15
+ "calendar": { "command": "npx", "args": ["-y", "some-calendar-mcp"], "env": { "TOKEN": "${CALENDAR_TOKEN}" } },
16
+ "docs": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${DOCS_TOKEN}" }, "agents": ["main", "gonzo"] }
17
+ }
18
+ ```
19
+
20
+ Servers of one agent go in its `agent.json`:
21
+
22
+ ```json
23
+ { "mcp": { "library": { "command": "library-mcp", "args": ["--stdio"] } } }
24
+ ```
25
+
26
+ Who gets what:
27
+
28
+ | Setting | Effect |
29
+ |---|---|
30
+ | `agents` on a global server | Which agents get it. Default: all (`["*"]`). |
31
+ | `globalMcp: true` in `agent.json` (default) | The agent gets every global server that includes it. |
32
+ | `globalMcp: false` | No global servers. |
33
+ | `globalMcp: ["web"]` | Exactly these global servers, whether or not their `agents` list names this agent. |
34
+ | A server in `agent.json` with a global server's name | Replaces the global one for this agent (an entry with `"enabled": false` does not: the global server stays). |
35
+ | `"enabled": false` | Switches a server off without deleting it. |
36
+
37
+ `pine check` prints the resulting list per agent.
38
+
39
+ ## Adding a server
40
+
41
+ Three ways, all ending in the same entry in `pine.json` (for everyone) or an `agent.json`:
42
+
43
+ **Ask an agent.** "Connect this MCP server: https://mcp.example.com/mcp", or "look at
44
+ example.com and install their MCP server". The agent calls `add_mcp_server` with the server's
45
+ URL, or for a local server with the command that starts it (`npx -y @example/mcp@latest`); you
46
+ get an approval dialog with the name, the URL or the command, and who gets it. Said just
47
+ like that, it is for the conversation you are in: only that conversation has the server's
48
+ tools, and the server is removed with the conversation (in an agent's main conversation it is
49
+ the agent's, in all its conversations). Say "for you as an agent" to keep it for the agent from
50
+ any conversation, and ask the **main agent** for "all agents": only it can add or remove a
51
+ server for everyone. `remove_mcp_server` takes a server out again. See [setup.md](setup.md).
52
+
53
+ If you allow it, the server is written to the configuration, without a restart. The agent
54
+ does not have the new tools in the turn in which it added the server, so pine calls it again
55
+ by itself as soon as that turn ends, in the same conversation, and it goes on with the tools.
56
+ You do not have to send a message, and there is no need for a new conversation. The question comes in every mode, bypass included, because
57
+ it changes pine itself. (Plan mode is the exception the other way: there the agent adds
58
+ nothing, and says what it would add.)
59
+
60
+ A server added in one conversation is missing in the agent's other conversations. `/mcp` in
61
+ the terminal UI says so: "only this conversation", or "only the conversation X of main, not
62
+ this one"; `pine mcp list` says "only the conversation X of main". The agent sees the same
63
+ with its `mcp_servers` tool, which also says for each server whether its tools are in the
64
+ agent's tool list (connected) or missing (it did not start, or it needs a sign-in). To have
65
+ such a server in every conversation of the agent, tell the agent "add it for yourself as an
66
+ agent", in the conversation that has it or in another: it adds the server again under the
67
+ same name with `scope: "agent"`, you confirm, and the entry of the one conversation is
68
+ replaced. A key the server needs is named again (`secrets`) and typed again in that dialog:
69
+ the one pine kept for the old entry goes with it.
70
+
71
+ A **local server** is a program that somebody else wrote and that keeps running while the agent
72
+ works. One that an agent adds therefore runs where the commands of the agent that uses it run
73
+ (`"sandboxed": true` in its entry): it reaches what that agent's shell reaches and nothing
74
+ more. For an agent in `safe` or `manual` mode that is its sandbox: its workspace, its private
75
+ home folder and the network, and pine's home is closed to the program by the operating system.
76
+ For an agent in `auto` or `bypass` mode (the main agent, unless you say otherwise) there is
77
+ no sandbox: the program runs with your rights, your home folder and the network, and nothing
78
+ of the operating system keeps it out of pine's home. Either way it gets nothing of the
79
+ daemon's environment. The dialog shows the exact command and says which of the two it is.
80
+ Read the command: it is what will run. The command is one program with its arguments; shell
81
+ operators (`&&`, a pipe, `$(...)`) are refused. Where the machine has no sandbox, an agent in
82
+ `safe` or `manual` mode cannot add a local server at all.
83
+
84
+ If a local server needs a sign-in, its documentation names a command for it (often the same
85
+ command with `login` at the end). The agent runs that in its shell and gives you the link it
86
+ prints. If it needs a key or token in its environment, the agent names the variable
87
+ (`secrets`, for example `EXAMPLE_API_KEY`) and never the key: the dialog has a field for it,
88
+ you type it there, and pine keeps it in `.env` and takes it out again with the server.
89
+
90
+ Your yes makes it a server of yours: using it does not mark the conversation as having read
91
+ outside content. It is written with `"approve": "tainted"`, which only matters after the
92
+ conversation has read something from outside (a web page, say): from then on the server's tools
93
+ that act ask each time, until you answer "Always here" in that dialog, which settles it for the
94
+ conversation. Its
95
+ read-only tools never ask. If the server itself returns other people's text (mail, tickets, a
96
+ web search), add `"taints": true` to its entry; if you want no questions at all, remove
97
+ `approve`.
98
+
99
+ **From a shell.**
100
+
101
+ ```bash
102
+ pine mcp add docs https://mcp.example.com/mcp
103
+ ```
104
+
105
+ ```bash
106
+ pine mcp add library --agent gonzo -- /usr/local/bin/library-mcp --stdio
107
+ ```
108
+
109
+ Options: `--agent <id>` (only that agent), `--taints`, `--approve always|tainted`,
110
+ `--timeout <seconds>`, `--description "..."`, `--exposure direct|codemode|deferred|hidden`.
111
+ `pine mcp list --offline` lists without connecting. A remote server needs an https URL (http only for
112
+ `localhost`). If a daemon is running the change applies at once; otherwise at the next start.
113
+ `pine mcp remove <name>` takes it out again (`--agent <id>` for one in an `agent.json`), and
114
+ `pine mcp list` shows every server, who gets it, and whether it connects:
115
+
116
+ ```
117
+ notes needs sign-in all: main
118
+ https://gateway.example/d/abc/mcp [outside content] [approval: tainted]
119
+ web connected all: main
120
+ bundled: web [outside content]
121
+ ```
122
+
123
+ **By hand.** Edit the file as described below, run `pine check`, restart.
124
+
125
+ ## Signing in (OAuth)
126
+
127
+ A remote server that answers "unauthorized" and supports OAuth needs you to sign in once:
128
+
129
+ ```bash
130
+ pine mcp login notes
131
+ ```
132
+
133
+ or `/mcp login notes` in the terminal UI. Your browser opens the server's sign-in page; when
134
+ you approve, pine stores the tokens in `data/pi/mcp-auth.json` (closed to agents) and refreshes
135
+ them on its own afterwards. Open conversations get the server's tools from their next message.
136
+ `pine mcp logout <name>` deletes the tokens.
137
+
138
+ The sign-in is pi's: it follows the server's OAuth metadata and registers itself as a client.
139
+ For servers that need a pre-registered client or a particular client name, add an `oauth`
140
+ block to the entry (`clientId`, `clientSecret`, `callbackPort`, `clientName`,
141
+ `clientRegistration`); pi's `docs/mcp.md` describes each. A server that takes a fixed token
142
+ instead needs no sign-in: put `"headers": { "Authorization": "Bearer ${TOKEN}" }` in the entry
143
+ and the token in `.env`.
144
+
145
+ ## Server entries
146
+
147
+ An entry has the shape of an `mcpServers` entry in pi's `mcp.json`:
148
+
149
+ | Key | Meaning |
150
+ |---|---|
151
+ | `command`, `args`, `env`, `cwd` | A local server started as a child process (stdio). |
152
+ | `url`, `headers` | A remote server (streamable HTTP). |
153
+ | `exposure` | How tools reach the model. pine's default is `direct`: every tool is declared. `codemode` offers one scripting tool instead, `deferred` makes tools searchable, `hidden` hides them. Use `deferred` or `codemode` for servers with dozens of tools. |
154
+ | `toolExposure` | Per-tool override, for example `{ "delete_*": "hidden" }`. |
155
+ | `description` | One sentence for the model about what the server offers. |
156
+ | `url` (remote servers) | Also decides where the `download` tool fetches from without asking: addresses on the same scheme, host and port. A server that hands out download links for its files on its own host works with it out of the box. See "Files and pictures from a remote server". |
157
+ | `headers` (remote servers) | Sent with every call to the server, and by the `download` tool with a link that one of the server's own tools returned in the conversation. Never with any other address, and never for a server with `taints: true`. |
158
+ | `timeout` | Seconds one call to this server may take before the agent is told it timed out. Default 60. Raise it for a server with slow tools, e.g. `"timeout": 180`. |
159
+
160
+ and the keys pine adds (besides `agents` and `enabled` from the table at the top):
161
+
162
+ | Key | Meaning |
163
+ |---|---|
164
+ | `pine` | Use a server that ships with pine (`"web"`, `"browser"`, `"commands"` or `"computer"`), configured through `options`. |
165
+ | `sandboxed` | For a local server: `true` runs its program where the commands of the agent that uses it run, with that agent's home folder and environment, instead of as a process of the daemon's: inside the sandbox for an agent in `safe` or `manual` mode, with your rights for one in `auto` or `bypass` mode. Written by `add_mcp_server` for every local server an agent adds. Add it to a server of your own to hold it the same way; take it out only if you trust the program with your account and pine's home. |
166
+ | `session` | In an `agent.json` only, written by `add_mcp_server`: the one conversation the server was added for. Other conversations of the agent do not get it, and it is removed with that conversation. |
167
+ | `taints` | `true` when the server returns content written by others (web pages, mail, tickets, chat). A session that calls it becomes tainted. Default `false`, `true` for the bundled `web`, `browser` and `computer`. |
168
+ | `approve` | `"always"`: every call needs your approval, each time (except in bypass mode, where nothing asks). `"tainted"`: once the session has seen outside content, the server's tools that act need approval (its read-only tools do not), and you can answer "always in this conversation"; use it for servers that change things or send things out. Default `"never"`. |
169
+
170
+ Each session starts its own copy of a local server and stops it when the session closes. A
171
+ local server that you added yourself (`pine mcp add <name> -- <command>`, or an entry you
172
+ wrote) is a normal process of yours: it is not sandboxed, and what it can reach, agents can
173
+ reach through it. Give it the narrowest credentials that do the job, or set `"sandboxed": true`.
174
+ One that an agent added has that from the start; it is in a sandbox when the agent is.
175
+
176
+ What a server says about its own tools counts in two places. A tool it declares read-only
177
+ (`readOnlyHint`) is not asked about (unless the server has `"approve": "always"`), and it is
178
+ the only kind of MCP tool that runs in plan mode:
179
+ search and page reading of `web`, a snapshot or a screenshot of the browser, looking at an app.
180
+ Every other tool is refused in plan mode, opening a page in the browser and the tools of a
181
+ `commands` server among them: pine cannot know that one of those only looks.
182
+
183
+ pi's `mcp.json` files are not read. The daemon gives pi a folder of its own (`data/pi`) and
184
+ agent sessions load no MCP configuration file, so servers you set up for your own interactive
185
+ pi do not appear in agents.
186
+
187
+ ## Files and pictures from a remote server
188
+
189
+ A server that makes files (pictures, sound, documents) keeps them where it runs. When it is
190
+ reached over the network, that can be another computer, and three things follow:
191
+
192
+ - **A picture in a tool's answer is already shown.** The terminal UI draws it where the tool
193
+ ran. pine adds a line to such an answer that tells the agent so, since a model that reads
194
+ only text sees a file name and a link there and no picture. The agent does not show it a
195
+ second time and does not fetch it unless you want the file. (The line is not added when the
196
+ answer goes to a chat such as Telegram, where nothing was drawn.)
197
+ - **A file path in an answer is a path on the server's computer.** On the agent's own disk
198
+ that file does not exist: `cp` and `read` answer "No such file or directory". The agent's
199
+ prompt names the servers that are reached over the network (every `url` that is not
200
+ `localhost` or `127.0.0.1`) and says so.
201
+ - **The agent gets the file with the `download` tool and the link from the answer.** A link on
202
+ the server's own address (same scheme, host and port as its `url`) is fetched without a
203
+ question. If the server has `headers` (its key), pine sends them with such a link itself:
204
+ only with an address that one of the server's own tools returned in this conversation, exactly
205
+ as it was returned, and not for a server with `taints: true`. The agent never sees the key and
206
+ cannot send it anywhere else. Any other address on the server is fetched without the key, and
207
+ a server that wants it answers HTTP 401: the agent calls the tool again and downloads the
208
+ link it gets. After a `/reset` or a restart of pine the links given before count no longer.
209
+
210
+ A server of your own that returns its files' paths is better off returning only a name and a
211
+ link: a path is of use to nobody who is not on the same computer.
212
+
213
+ ## Bundled: web
214
+
215
+ Search and page reading without a browser.
216
+
217
+ ```json
218
+ "web": { "pine": "web", "options": { "braveApiKey": "${BRAVE_API_KEY:-}" }, "agents": ["scout"] }
219
+ ```
220
+
221
+ | Tool | What it does |
222
+ |---|---|
223
+ | `mcp__web__search(query, count?)` | Web search. Uses the Brave Search API when `braveApiKey` is set, otherwise DuckDuckGo's HTML page (fine for light use; it may rate-limit). |
224
+ | `mcp__web__fetch(url, max_chars?, start?)` | Fetches a page and returns its text. `start` continues a long page. |
225
+
226
+ | Option | Default | Meaning |
227
+ |---|---|---|
228
+ | `braveApiKey` | none | Brave Search API key. |
229
+ | `allowHosts` | all | Only these hosts (and their subdomains) can be fetched. Without `braveApiKey` the search is such a fetch too: add `duckduckgo.com`. |
230
+ | `denyHosts` | none | These cannot. |
231
+ | `allowPrivate` | `false` | Allow every address on this computer and your own network, without asking. Leave it off: this server never asks. To look at one local address the agent uses the browser, which asks you for that address, see "Local addresses" below. |
232
+ | `maxBytes` | 2 MB | Cut-off for one response. |
233
+ | `maxUrlLength` | 2000 | Longer URLs are refused, which limits how much can be smuggled out in one. |
234
+ | `timeoutMs` | 20000 | Per request. |
235
+ | `userAgent` | a desktop Safari | What the server says it is when it fetches a page. |
236
+
237
+ It only speaks http and https, follows redirects itself and checks every hop, and refuses
238
+ loopback, private, link-local and similar addresses at the moment the connection is made. A page
239
+ therefore cannot send an agent to your router, your NAS or pine's own control port. Results are
240
+ wrapped in markers that say they are outside content, and the server is marked `taints`.
241
+
242
+ Once you have agents with private files, move `web` and `browser` to a research agent that has
243
+ nothing private in its workspace and let the others delegate to it.
244
+ [security.md](security.md) explains why.
245
+
246
+ ## Bundled: commands
247
+
248
+ Turns fixed commands into typed tools, so an agent that should "check the printer" does not
249
+ need a shell for it.
250
+
251
+ ```json
252
+ "tools": { "pine": "commands", "agents": ["house"], "options": { "commands": {
253
+ "printer_status": {
254
+ "description": "Current state of the Bambu printer as JSON",
255
+ "run": ["/opt/homebrew/bin/mosquitto_sub", "-h", "192.168.1.50", "-t", "device/{{serial}}/report", "-C", "1", "-W", "5"],
256
+ "params": { "serial": { "description": "Printer serial", "pattern": "[0-9A-Z]{15}" } },
257
+ "timeoutSec": 10
258
+ },
259
+ "disk_usage": { "description": "Free space on the data volume", "run": ["/bin/df", "-h", "/Volumes/data"] }
260
+ } } }
261
+ ```
262
+
263
+ | Key | Meaning |
264
+ |---|---|
265
+ | `description` | What the model reads. |
266
+ | `run` | Program and arguments. `{{name}}` inserts a parameter. |
267
+ | `params.<name>` | `type` (`string`, `number`, `boolean`), `description`, `enum`, `pattern` (must match the whole value), `default`, `required` (default true). |
268
+ | `timeoutSec` | Default 30. |
269
+ | `cwd`, `env` | Working folder (default: where the conversation's tools start: the agent's workspace, or the folder opened for the conversation) and extra environment. |
270
+ | `sandbox` | `true` runs the command inside the agent's sandbox (the variant in which instruction files are read-only). It has no effect on a machine without a working sandbox. Default `false`: these are your commands, and most need the network. |
271
+ | `maxOutput` | Characters of output returned. Default 30000. |
272
+
273
+ Arguments are passed as a list, never through a shell: a parameter value of `x; rm -rf ~` is one
274
+ harmless argument. A value that starts with `-` is refused unless the parameter is a number or
275
+ has a `pattern` or `enum`, so the model cannot turn a value into an option. Constrain parameters
276
+ with `pattern` or `enum` wherever you can.
277
+
278
+ Mark a commands server `"approve": "tainted"` if any of its commands changes something.
279
+
280
+ ## Bundled: browser
281
+
282
+ A real browser, for pages that need JavaScript, clicks, forms or a login. It is Microsoft's
283
+ Playwright MCP server with a guard around it.
284
+
285
+ ```json
286
+ "browser": { "pine": "browser", "options": { "headed": false } }
287
+ ```
288
+
289
+ `pine init` downloads the browser itself; `pine browser-install` fetches it again after an update.
290
+
291
+ The tools appear as `mcp__browser__browser_navigate`, `..._snapshot`, `..._click`, `..._type`,
292
+ `..._fill_form`, `..._press_key`, `..._select_option`, `..._hover`, `..._wait_for`, `..._find`,
293
+ `..._tabs`, `..._navigate_back`, `..._handle_dialog`, `..._close`, `..._take_screenshot`,
294
+ `..._console_messages`. A page is read as a snapshot: a text outline in which every element has
295
+ a reference the click and type tools take. To see what a page looks like, the agent takes a
296
+ screenshot, which a model that can see pictures gets as a picture; to see why a page it built
297
+ does not work, it reads the page's console messages.
298
+
299
+ ### Seeing the browser, and logging in yourself
300
+
301
+ The browser has no window: the agent works in it unseen. When you want to watch, or a page
302
+ needs you (a login, a captcha, a payment to confirm), ask the agent to show the browser. It
303
+ has two more tools for that in your own conversations, and nothing in the configuration has to
304
+ change:
305
+
306
+ | Tool | What it does |
307
+ |---|---|
308
+ | `mcp__browser__browser_show` | The browser becomes a window on the screen of the computer pine runs on, on the page the agent is on, with the same logins. You can click and type in it; the agent goes on working in the same window. Takes about a second |
309
+ | `mcp__browser__browser_hide` | The window closes and the browser goes on without one, on the same page, with the same logins |
310
+
311
+ - While the window is open you and the agent share one browser. The agent is told so, and that
312
+ what you ask for on the web is to be done in that window, on the page you are on, not with a
313
+ web search.
314
+ - The agent does not act on a page it has not seen. Before each of its calls pine compares the
315
+ tabs with what the agent last saw. If you opened a page or a tab meanwhile, the agent is
316
+ moved to it, and a call that would act (open another address, click, type, close a tab) is
317
+ not carried out: the agent gets your page instead and is told to work there, or to open a
318
+ new tab for anything else. So a page you opened is not replaced behind your back. A call
319
+ that only looks (a snapshot, a screenshot) goes through, on your page.
320
+ - The page is loaded again when the window appears or goes, so text typed into a form is lost
321
+ and has to be typed again. Cookies and the site's stored data are kept; where several tabs
322
+ were open, the one in front comes back.
323
+ - What you log in to in the window, the agent is logged in to as well: it is one browser.
324
+ Without `profile` the logins last as long as that conversation's browser runs: at the
325
+ latest until pine restarts or the conversation is reset. With `profile` they are kept.
326
+ - A run that was started from outside (an event, a message from somebody else) does not have
327
+ these tools and cannot put a window on your screen.
328
+ - On a machine without a screen (a server, Docker) no window can open. The agent is told so
329
+ and carries on without one.
330
+ - `"block": ["browser_show", "browser_hide"]` takes the tools away. `"headed": true` starts the
331
+ browser with a window every time.
332
+
333
+ | Option | Default | Meaning |
334
+ |---|---|---|
335
+ | `headed` | `false` | `true`: the browser has a window from the start, in every conversation. To see it now and then, ask the agent instead (`browser_show`). |
336
+ | `profile` | none | A folder for a persistent profile: cookies and logins survive. Without it every session starts clean. |
337
+ | `images` | `true` | `false`: a screenshot comes back without its picture. Set it for a model that cannot see pictures. |
338
+ | `tools` | `"core"` | `"core"`: the sixteen tools above. `"all"`: everything Playwright offers that is not blocked. Or a list of names. |
339
+ | `block` | `[]` | Further tool names to withhold. |
340
+ | `allowHosts`, `denyHosts` | none | Limit where the browser may go. Subdomains are included. |
341
+ | `allowPrivate` | `false` | Allow every address on this computer and your own network, without asking. Leave it off: one local address at a time is allowed by answering a question, see "Local addresses" below. |
342
+ | `browser` | `chromium` | `chrome` or `msedge` use an installed browser instead of Playwright's Chromium. |
343
+ | `executablePath`, `viewport`, `caps`, `extraArgs` | | Passed on to Playwright MCP. With `"caps": "storage"` and `"tools": "all"` the agent also gets the tools that read and change cookies. |
344
+
345
+ What the guard does:
346
+
347
+ - **No local network, unless you say yes.** Everything the browser requests goes through a
348
+ proxy inside the guard, which refuses loopback, private and link-local addresses, judged on
349
+ the address it actually connects to. A page cannot reach your router, your NAS, the model
350
+ server or pine's control port, whether by link, redirect, script or DNS trick. The one
351
+ exception is an address you allowed for a conversation ("Local addresses" below). `file:`
352
+ URLs are blocked by Playwright.
353
+ - **No code on your machine.** `browser_run_code_unsafe` (runs code in the server process),
354
+ `browser_file_upload` and `browser_drop` (hand local files to a page), `browser_install`, and
355
+ `browser_storage_state` and `browser_set_storage_state` (write and read a file of cookies)
356
+ are removed from the tool list and refused if called, whatever `tools` says. Tools that a
357
+ page itself declares (WebMCP) are not collected.
358
+ - **One step at a time.** Calls a model issues in parallel are run one after another; a browser
359
+ has one page in front.
360
+ - **Snapshots inline.** Playwright writes snapshots to files; the guard puts their content into
361
+ the tool result (cut at 24,000 characters; `browser_find` locates things on longer pages).
362
+ A screenshot comes as a picture, with the name of the file it was saved as. One that gives
363
+ up because the page is still loading its fonts is taken a second time.
364
+
365
+ A browser is the widest door for outside content: sessions that use it are tainted, and with a
366
+ `profile` it is signed in as you wherever you signed in. Treat a persistent profile like a
367
+ password; do not give it to an agent that also handles untrusted events.
368
+
369
+ ### Local addresses
370
+
371
+ An agent that builds a web page wants to look at it: a development server on
372
+ `http://localhost:5173`, or a device at `http://192.168.1.20`. The browser cannot reach those by
373
+ itself. When the agent opens one with `browser_navigate`, pine asks the owner first, like any
374
+ approval. The agent does not call another tool for this and does not need `request_access`: it
375
+ opens the address and waits.
376
+
377
+ - A yes allows that host and that port, for that conversation and its sub-agents, until the
378
+ conversation is reset or the daemon restarts. `localhost:5173` and `127.0.0.1:5173` are two
379
+ questions; so are two ports.
380
+ - A no blocks the call. The agent should not try another spelling of the address, or start a
381
+ browser of its own from the shell instead.
382
+ - Only what the agent itself opens is asked about. What a page loads, links or redirects to on
383
+ another local address is refused. If the page really needs it (an API on another port), the
384
+ agent opens that address with `browser_navigate` once, which asks.
385
+ - Asked about are addresses that are local by their own name: `localhost`, names ending in
386
+ `.localhost`, `.local` or `.internal`, and IP addresses in private ranges. A name that only
387
+ turns out to be local when it is looked up (`nas.home`) is refused without a question; for
388
+ that the owner sets `allowPrivate`.
389
+ - pine's own control port is never opened, and never asked about.
390
+ - In bypass mode there is no question. A run that an event from outside started cannot ask at
391
+ all. In a conversation that has read outside content the question says so.
392
+ - `allowHosts` and `denyHosts` still apply.
393
+
394
+ A server the agent starts from its own shell (`npm run dev`) can only listen on a port when the
395
+ shell has network access. The main agent has it (`auto` mode); an agent in the sandbox
396
+ (`safe` or `manual` mode) needs `request_access` with `network: true`, or `sandbox.network`.
397
+ Start the server in the background and give it a moment before opening the page. An agent in
398
+ `auto` mode can also stop it again with `kill`; in the sandbox a command cannot stop what an
399
+ earlier command started.
400
+
401
+ ## Bundled: computer
402
+
403
+ Operating the apps on the Mac pine runs on: reading a window as an outline, pressing its
404
+ controls, clicking in a picture of it, typing. macOS only.
405
+
406
+ ```json
407
+ "computer": { "pine": "computer" }
408
+ ```
409
+
410
+ It is given only to an agent that reaches the owner's whole account, in the owner's own
411
+ conversations, and the owner is asked once per app in a conversation. The tools, the two ways
412
+ to work (by outline for any model, by picture for one that can see), what macOS has to be told
413
+ and the options are in [computer.md](computer.md).
414
+
415
+ ## Telegram, MQTT and other outputs
416
+
417
+ Sending a Telegram message or an MQTT command is not an MCP server. Both are event sources
418
+ that can also send, and an agent uses its `send` tool for them: the daemon already holds the
419
+ connection, and the source decides who may be messaged and which topics may be written. See
420
+ "Sending through a source" in [sources.md](sources.md).