项目的 README,来自 github.com/pmndre/pine。合并为一个 markdown 文件:README.md。
npm install -g @pmndre/pine
Most harnesses just do input chat: "Do this do that". And maybe a scheduler: "Do it tomorrow". In PINE agents react to any stimuli. From watching folders, commands, websites, ftp endpoints, webhooks, to any other event source. You can hook them up and let them react to and operate your physical devices in the house, or digital assets.
PINE of course also handles regular chat, coding, tasks and orchestration. Agents carry memory and so on. All the basic stuff is in there, too.
*.ts service with a schema. Tell the agent what you want and they subscribe: "Watch ~/documents/scans, for every new file: extract summaries and payment details, if present"/goal keeps an agent working until it is done).[!IMPORTANT] pine runs on macOS and Linux;
pine initsets up what it needs. Windows users can try Docker. It remains open what exactly is necessary to make it run completely in Windows.
you: terminal UI · Telegram
│
▼
wake it ┌───────────┐ it uses
events ───────────────► │ │ ◄───────── MCP servers
Telegram · MQTT · FTP │ │ ◄───────── skills
webhooks · folders │ agent │
web addresses │ │
commands · etc * │ │
schedules ────────────► │ │
repeating · once └─────┬─────┘
│ delegate ──► other agents
│ subagent ──► with distinct prompts, in parallel
▼
answers · messages · actions
Events, schedules, MCPs and skills can be set up by asking:
for the current conversation, agent scope, or globally
(main agent only) for all agents.
* New event types that agents can subscribe to can be created easily.
Sets everything up: the browser the web tools drive, and your user folder (~/.pine). On Linux
also the sandbox that agents in safe mode work in; it shows what it would install and asks once.
pine init
Checks the setup: validates the configuration, lists each agent with its model, tools and MCP servers, and prints security notes if something is open that should not be.
pine check
Opens the terminal UI. If no daemon is running, it starts one inside and stops it when you quit.
pine
Runs the daemon as a service, without the UI, so agents keep reacting to events with no terminal
open. pine then attaches to it. To have it start at login, see
operations.md.
pine start
Connect your subscriptions, or local llm servers. Switch with /model in the UI:
pine login opencode-go
pine login anthropic and pine login openai-codex use a Claude or ChatGPT subscription. A
model server of your own (llama.cpp, vLLM, LM Studio) is added by its address, with
pine model add studio http://127.0.0.1:8080, or by asking the main agent. See
operations.md and tui.md.
To work on a project, start it in that folder. The agent gets that folder for the
conversation, and ▤ code (or ctrl+g) opens a pane with git changes and diffs, the files and
the output of its tool calls. /undo takes your last message back, with the files it changed
(coding.md):
pine .
There is also a desktop app for macOS, with the same conversations in a window, an editor for
a conversation's folder and a settings panel for agents, models, MCP servers, skills and
events. It starts pine itself, or uses the one that runs (desktop.md).
Each release has it as a disk image, for
Apple silicon and for Intel. It carries pine and the Node it runs on, so nothing else has to
be installed, and it gives your shell the pine command. From a checkout:
npm run desktop
To get a newer version later, with whatever it needs:
pine update
A container needs nothing special. It is the wall around pine, and the agents work inside it without a sandbox of their own:
docker run -it -v pine:/root/.pine node:24 bash
-v pine:/root/.pine keeps pine's home (configuration, conversations) when the container is
replaced. Inside, it is the same as anywhere:
npm install -g @pmndre/pine
pine init
Every agent whose mode you did not choose then works in auto mode, and pine check says so.
The agents and pine's own secrets are in the same container; what keeps the two apart there is
described under "pine's own files without a sandbox" in
docs/references/security.md.
safe mode puts an agent into a sandbox of its own, as on a Mac. A container may only make
one when it is started with the rights for it, which take away most of what Docker itself
protects:
docker run -it --cap-add SYS_ADMIN --cap-add NET_ADMIN --security-opt seccomp=unconfined --security-opt apparmor=unconfined -v pine:/root/.pine node:24 bash
| Part | What it is for |
|---|---|
--cap-add SYS_ADMIN |
lets the sandbox create its namespaces |
--cap-add NET_ADMIN |
lets a sandbox without network have its own loopback interface |
--security-opt seccomp=unconfined |
Docker's system call filter forbids the sandbox's change of root |
--security-opt apparmor=unconfined |
Docker's AppArmor profile forbids its mounts |
pine init installs what the image lacks (bubblewrap, the browser's system libraries) and says
so if a right is missing. With pine as an ordinary user in the container instead of root, add
--security-opt systempaths=unconfined. --privileged works in place of all of them.
Start at docs/SKILL.md; it indexes everything.
| To do this | Read |
|---|---|
| Understand how the pieces fit | overview.md |
| Use the terminal UI | tui.md |
| Use the desktop app (macOS): conversations, an editor, and a settings panel in one window | desktop.md |
Work on a project: pine ., the code pane with git changes, files and tool output, /undo |
coding.md |
| Let an agent make a web page you click in, as its user interface, and be woken by what you press | interfaces.md |
| Install, run, use the CLI, run it as a service | operations.md |
Write pine.json and agent.json |
configuration.md |
| Let agents set things up by tool call instead of editing files | setup.md |
| Set up agents, delegation and sub-agents; how tools are declared and what stays cached | agents.md |
| Route events, schedules, model calls | events.md |
| Event sources: setting one up, subscribing, sending, secrets, trust | sources.md |
| Every source type: Telegram, folders, MQTT, web addresses, feeds, mail, Slack, cameras | source-types.md |
| MCP servers, web search, command tools | mcp.md |
| Let an agent operate the apps on your Mac | computer.md |
| Know what is protected and what is not | security.md |
| Work on pine itself | AGENTS.md, stack.md |