> ## Documentation Index > Fetch the complete documentation index at: https://mcpjam-mintlify-docs-update-pr-3812-1786323532738.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Computer > A personal cloud Linux workstation for your project — open a terminal, run tools, and give your agents a real bash environment The Computer is available on accounts where the feature has been enabled. The **Computer** tab only appears when it is active for your account. Each project gives every member an opt-in **Computer**: a personal cloud Linux workstation with a web terminal and a `bash` tool your agents can call. It boots from a base image (Debian + Node + Python) or a custom [sandbox image](#sandbox-images) you define, sleeps automatically after about 30 minutes idle or shortly after you close the terminal, and wakes on next use. Open it from the **Computer** tab. The first time you open the terminal, MCPJam provisions the machine; after that it resumes in about a second. ## "This machine" engine In addition to the cloud computer, the Playground supports running the `bash` tool directly on the machine that runs this inspector — the **"This machine"** engine. When it is active, agent commands execute as your OS user account in a per-project workspace under `~/.mcpjam/computer//`, with no cloud sandbox involved. ### Consent Before the local engine can be used, you must explicitly grant consent from the inspector. Consent is a device-scoped capability: it records that you — the person running this inspector — have allowed agents to execute commands on this machine. Granting consent from a second browser profile rotates the capability, and the previous profile is asked to re-consent. Consent can be revoked at any time. After revocation, any turn that requests the local engine resolves as unavailable rather than silently falling back to the cloud. ### Approval Every command that runs on the local engine requires your explicit approval before it executes, regardless of the host's tool-approval setting. There is no auto-approve for model-driven shell commands on your own machine. ### Engine label Tool results from non-hosted turns include an `engine` field — `"local"` or `"cloud"` — so you can see at a glance where a command ran. Hosted inspector deployments omit this field to keep transcripts byte-identical to their existing format. ### What the local engine is not The local workspace directory is a convenient default working directory, not a sandbox. Commands run with your full OS user permissions. The boundaries are consent, per-command approval, and the actor restrictions below — not filesystem paths. ### Who can use it The local engine is available only to signed-in members running the inspector directly (not via a shared chatbox link, a guest session, a journey, or a swarm scope). Requests from those contexts always resolve to the cloud family. ## Chat attachments When the previewed host has a computer attached and you are signed in, files you attach in the chat composer are uploaded into the computer's filesystem at **`/home/user/attachments/`** in addition to being sent inline to the model. A short note is appended to your message so the model — and any MCP server running on the computer — can reference the files by path: ``` [Attachments uploaded to the computer — use the bash tool to read them] - report.csv: /home/user/attachments/ab12cd34-report.csv ``` If the upload fails (for example, because the daily start cap is reached or the storage quota is exceeded), the send is **aborted** and the composer is left intact — your message and attachments are never sent without the files landing on the computer first. This only applies when the host config attaches a personal computer and you are signed in. Guest sessions and hosts without a computer attached keep the existing inline-only behavior. ## Agent tools When the **Computer** tab is open, agents have access to four tools for managing the computer's lifecycle. These tools are only available while you are on the Computer screen and require a signed-in project. | Tool | What it does | | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ui_start_computer` | Provisions the computer on first use, or wakes it if it is asleep. Counts against the daily start cap — a cap rejection is returned as an error and the start is refused. | | `ui_hibernate_computer` | Puts the computer to sleep immediately. Non-destructive: files and state are preserved. | | `ui_reset_computer` | Resets the computer to its image, **wiping all files**. Requires confirmation. | | `ui_delete_computer` | Tears the computer down entirely, **deleting all files**. Requires confirmation. | Opening the interactive terminal is a human action and is not available as an agent tool. The terminal token never appears in the agent transcript. Agents can check the computer's current state (lifecycle status, environment, whether a terminal is open) via the app snapshot (`ui_snapshot_app`) while on the Computer screen. ## Sleep and hibernate Your computer sleeps automatically when it has been idle for about 30 minutes, or shortly after you close the terminal. Sleeping is non-destructive — the disk and memory are snapshotted and restored on wake, so everything you left running is still there. To put the computer to sleep immediately, click **Hibernate now** in the Computer tab toolbar (only visible when the computer is running). You'll be asked to confirm, then the terminal closes and the machine hibernates. It wakes automatically the next time you open the terminal or an agent calls the `bash` tool. ## Sandbox images A sandbox image is a custom image your computer boots from, defined by a **blueprint** — a small YAML file: ```yaml theme={null} # base must be an allowlisted official image (debian, ubuntu, node, python) # pinned by an immutable @sha256 digest. base: debian:bookworm-slim@sha256:<64-hex-digest> # Baked into the image at build time. initialize: - name: Install tooling run: apt-get update && apt-get install -y git jq # Handed to the agent as reference — NEVER run automatically. If deps look # stale, the agent can run these itself via bash. maintenance: - name: Refresh deps run: cd ~/app && npm install # Model-facing notes, injected into the agent's context whenever a chat # turn runs with the bash tool on a computer booted from this image. knowledge: - name: Test notes contents: Run `make test` before pushing. ``` The editor lints as you type (the backend is the single validator; the CLI has `mcpjam images validate` for the same check). Build the image, then **Use on computer** to boot from it. `base` / `initialize` edits need a re-build; `maintenance` / `knowledge` edits take effect at the next chat turn without one. Images can be kept private to you or shared with the whole project. Manage them from **Change** on the image strip. Image definitions (their blueprints) live in the project database, not on any one computer's disk — see [Data & persistence](#data-and-persistence). ## Chatbox sandbox When a chatbox is backed by an environment that has a pinned computer image, the `bash` tool runs on a **per-conversation ephemeral sandbox** booted from that image — not on your personal computer. ### How it works * **Per conversation.** Each new conversation gets its own isolated machine. Files you write and packages you install in one conversation are not visible to any other conversation. * **Persistent across turns.** Within a single conversation, the same sandbox is reused on every turn — you can write a file on turn 1 and read it on turn 5. * **Reaped after idle.** If a conversation goes idle for a long time, the sandbox is deleted (not paused). When that happens, you'll see a notification in the chat: *"This conversation's sandbox was reset after being idle — files and shell state from earlier turns are gone."* * **Image from the environment.** All members on the same chatbox boot from the same environment image, so the machine is consistent regardless of who is chatting. * **No bash if the image is unavailable.** If the environment's image can't boot right now, the chatbox loads normally without a `bash` tool — no error, and no fallback to your personal computer. ### What is unchanged * **Your personal computer** is unaffected. Nothing a chatbox conversation writes lands on your personal computer, and nothing on your personal computer is visible inside a chatbox sandbox. * **Host-backed chatboxes** (those not tied to an environment) continue to use your personal computer as before. * **Environments with no pinned image** also continue to use your personal computer as before. ## Data & persistence Your computer is **scratch space, not durable storage.** Treat it like a fresh dev box you can rebuild at any time — convenient and fast, but not a place to keep the only copy of anything. Files persist when your computer sleeps, but they aren't backed up — keep anything important in git or elsewhere. ### What persists * **The filesystem.** When your computer sleeps, its entire disk and memory are captured in a pause snapshot and restored on wake, so files you created and tools you installed are still there when you come back. ### What wipes it Each of these rebuilds the machine from its image and **deletes every file on the disk**: * **Reset** — restores the computer to a clean copy of its current image. Reset sits on the image strip (next to **Change**) and is available once the computer is ready or asleep. * **Changing the image** — switching to a different environment (or back to the base image) rebuilds from that image. * **Delete** — tears the computer down entirely. * **Guest inactivity** — computers owned by signed-out (guest) sessions are deleted when idle instead of paused, so their files don't carry over between sessions. Sign in for a computer that sleeps and resumes with its disk intact. ### What survives independently These live in the project database (Convex), not on the computer's disk, so they are unaffected by reset, image changes, or deletion: * **Cloud skills** attached to the project. * **Image blueprints** — the definitions of your custom images. Deleting a computer never deletes your sandbox images; you can boot a fresh computer from the same image again. ### The no-backup caveat There is no backup and no volume behind the computer — the pause snapshot *is* the storage. Once the disk is wiped by any of the actions above, its contents are gone for good. Anything you want to keep should live in version control, a remote, or another durable store.