Your assistant's environment

Your Plank assistant doesn't run on your computer. It works on a private machine in the cloud — its own dedicated workspace — and reaches you through chat. Knowing that setup explains what it can do directly, what it needs your help with, and where your files live.

This page is written for both you and the assistant itself: the assistant can fetch it at https://plank.md/help/environment.md when it needs to reason about its own limits.

Where your assistant runs

The assistant runs on a remote machine that you can't see or touch directly — there's no shared screen, terminal, or browser between you and it.

• It runs commands itself. It will never ask you to "run this in your terminal" — it does the work on the machine for you.
• No desktop apps. It can't drive desktop applications on the machine.
• It tries a service's API first, and asks before opening a cloud browser. When work needs a website with a sign-in, the assistant looks for an API path before it asks to open a private cloud browser through the Browser panel — then it works inside the site. See Browser access. (This is a managed cloud browser, not a browser on the machine itself. Browser access is a beta feature — turn on Browser access under Settings → Preferences → Beta features.)
• It tells you what it did. Since you can't watch over its shoulder, it reports what it ran and what came back.

Signing in to other services

For an API key or token, the assistant just asks you for it. For a website you log into, use the Browser panel (see Browser access). For an OAuth connection, connecting an account uses a simple relay:

1. The assistant gives you a sign-in link.
2. You open it in your own browser and approve access.
3. You'll land on a page that doesn't load (often a localhost address) — that's expected.
4. You copy that final address from your browser's bar and paste it back into the chat.
5. The assistant completes the connection from there.

It can't catch a sign-in redirect on its own machine, which is why this hand-off exists. Many services skip it entirely — see Integrations for one-click connections.

What persists, and what doesn't

Some places on the machine keep their contents; others are wiped whenever the workspace restarts.

The practical upshot: the assistant saves anything important — tokens, settings, downloaded data — into durable storage, never a temporary folder. You don't manage this; it's just why your work and your connections are still there when you return.

Shared chats have their own home folder

A private chat runs on your own machine; a shared team chat runs on the workspace's machine. Both see the same workspace files, but each has a separate private config area. A sign-in or an install kept there in a private chat is invisible in a shared chat, and the other way round. That's why the assistant keeps connections and the packages its scripts need with the workspace scripts, under scripts/<provider>/ — the one place both kinds of chat see.

For the assistant: never npm install into .opencode/node_modules. It is the machine image's plugin tree mounted into the workspace — what you add there exists on one machine only and is gone when that machine is recreated, and .opencode/package.json is rewritten from the image on every start. Put a script's dependencies next to the script: npm install --prefix scripts/<provider> <package>. Details: Workspace scripts.

For the assistant: the specifics of what's installed on the machine — the interpreter name, where Python packages live, which common binaries are absent, and which scratch paths are writable — are in Running commands on the machine. Read that before your first shell command in a workspace.

Your workspace sleeps when idle

To stay efficient, a workspace goes to sleep when you're not using it and wakes on your next message. Waking is quick.

One consequence: the assistant can't count on a program it started staying alive between your requests. Rather than leaving something "running in the background," it writes results to your files so the next request picks up from there. (See Workspaces for what's shared across workspaces and the one-task-at-a-time behavior.)

Each workspace keeps its own accounts

You might have one workspace for personal work and another for your job, each tied to different accounts. The assistant keeps every connection scoped to the workspace it belongs to — a credential set up in one workspace is never reused in another. That's what stops a personal account from leaking into a work workspace, and the other way round. Inside one workspace, a connection saved under scripts/ works in private and shared chats alike; one kept in a chat's home folder does not.

Connecting external services

When you ask the assistant to wire up an outside service, it follows a tidy convention so the connection appears in your Integrations sidebar: it saves the script under scripts/<provider>/<service>/ and tags it with a @plank-integration header. You don't need to know the details — but if you're curious, Workspace scripts & the sidebar explains the header, and Integrations covers the ready-made connections.

Letting your assistant respond to incoming messages

Beyond running on a schedule, your assistant can react to incoming events — like a message on Telegram or WhatsApp. You connect a channel in chat (for Telegram: create a bot with BotFather and hand over the token; for WhatsApp Business: a Meta app with a phone number and access token), and the assistant wires up a trigger that wakes it when a message arrives. You stay in control of when it responds — every message, or only when it's mentioned — and its standing instructions, from Settings → Automations → Triggers. The assistant can adjust those too, and you'll see who changed what.

Running scripts from a dashboard

An HTML dashboard in your workspace can run one of these scripts at the press of a button. Those button-runs have sensible guard rails — a short per-script cool-down, a limit on how many run at once, and a time budget so nothing runs away. Interactive HTML dashboards covers how to set one up.

Images and naming in HTML files

When an HTML file shows an image from your workspace, the image path is read relative to the folder the HTML file lives in — not the workspace root. So chart.png loads from the same folder, images/q4.png from a subfolder, and ../shared/logo.png from one level up. A leading slash (/chart.png) is treated the same as same-folder, not the workspace root, so root-style or absolute paths won't load. The simplest reliable habit: keep an image in the same folder as the HTML file and reference it by name. Interactive HTML dashboards has the full rules.

HTML files also get descriptive, content-specific names — q4-revenue-report.html, acme-invoice.html — rather than a generic index.html. A workspace builds up many HTML files across many folders over time, and meaningful names keep them easy to find and tell apart.