Use the computer

Call devices first. Pass the selected UUID as deviceId on every hosted operation call. For MCP, discover current inputs with tools/list.

Read or change a file

Use files_read with path, files_write with path and content, or files_edit with path, oldText, and newText. These tools accept UTF-8 text up to 1 MB. Paths must be absolute or start with ~/.

files_write replaces the file. files_edit replaces text that must match exactly once. Read the file before editing and check the destination before overwriting it.

Run a command

Call shell_exec with command and, when needed, cwd and timeoutMs. The timeout is at most 55,000 milliseconds. It runs as the computer user who installed the helper. Shell access includes files outside any file-tool folder limits.

Check stdout, stderr, and code. A nonzero exit code means the command finished with an error.

If the result is outcome_unknown, the command may have run. Inspect operations or the resulting files. Never automatically repeat it. Reusing a request ID rejects duplicate execution; it does not replay the earlier result.

Transfer a file

For files too large for text tools, use a transfer. The agent host must save downloaded bytes itself; hosted MCP cannot write to its filesystem.

For large files:

• Download: call bulk_export, poll bulk_status until ready, then fetch downloadUrl with your own download tool.
• Upload: follow the part-upload steps below, then poll bulk_status until completed or failed.
• Stop or clean up: call bulk_cancel. It deletes temporary cloud data, not a file already delivered to the computer.

Keep the same agent token for the whole job. Download links are private and short-lived. Jobs last up to one hour and support files up to 10 GiB. Temporary cloud storage is not a backup.

For small binary files, call transfer_start, send zero-based chunks with transfer_chunk using transferId, index, and base64, then call transfer_finish. Each chunk is at most 192 KB before base64 encoding. To download, call transfer_pull and set offset to the returned nextOffset until done is true.

Upload parts for a large file

1. Call bulk_upload with deviceId and the exact byte size.
2. Use the returned partSize. Add a one-based partNumber query parameter to uploadUrl, preserving its existing query parameters. PUT each binary part with Content-Length and X-Content-SHA256, the lowercase hex SHA-256 of that part. For an empty file, send one empty part.
3. POST to completeUrl after all parts succeed.
4. Call bulk_import with deviceId, transferId, and the destination path.

For REST bulk calls, supply a UUID requestId. Export and upload use it as the transfer ID, so inspect that ID with bulk.status if the start response is lost. Never automatically start another job for an unknown outcome.

Use the browser

The person must approve browser access separately. Approval covers every open tab in the selected Chrome or Helium profile, including signed-in pages.

Call browser_call with name: "tools/list", then use a returned tool name and its inputs. The helper starts Chrome DevTools MCP when needed. For a separate browser with copied logins, follow browser sessions. The person imports locally; call profiles/list and pass the chosen profile UUID on each browser call.

If browser_installing is returned, no browser action ran. Wait a few seconds and retry the call while the helper installs Chromium in the background. Do not automatically retry outcome_unknown. Live attach to daily Chrome/Helium is removed; both legacy browser values select the same managed profile.

Use local MCP servers

Call mcp.servers to list servers the person already configured for Claude, Claude Code, Codex, Cursor or Windsurf on that computer. It returns ids, names and sources, never commands or secrets. Call mcp.tools with { server } to see a server's tools, then mcp.call with { server, tool, arguments }. Stdio servers start for the call and stop afterwards. Calls run with the server's own permissions; the Terminal sandbox does not apply.

Read a Terminal result

Terminal commands run in a sandbox by default. Writes outside approved folders and the temp folder, reads of credentials or browser data, and connections to local network addresses fail. The result's sandbox.blocked is true and stderr contains a <sandbox_violations> block saying what was refused. Tell the person; do not try to work around it. update_helper_for_terminal_sandbox means the computer's helper is too old to sandbox: ask the person to rerun setup, or to allow full Terminal access. Temporary connections never include Terminal.

Handle an unavailable computer

• Offline: Choose queue or discard based on the task. Use the queue flow below for authorized work that should run when the computer returns.
• Expired or revoked: Request a new connection and local approval.

The operations tool returns recent operation metadata. The helper also keeps a bounded log at ~/.ezremote/activity.jsonl. Revocation and cancellation block new work but cannot guarantee stopping an operation already sent.

Queue work explicitly

A normal operation reports device_offline without scheduling work. Choose queue or discard based on the task, including authorized proactive work. Queueing is an agent decision; it does not need another human confirmation for already authorized work. Expired and revoked access still blocks work.

1. Call queue_operation with { deviceId, operation, args, requestId }. Every operation name from tools/list can queue, using its dotted API name such as files.read or bulk.export. Generate and save a fresh UUID first. Do not reuse the ID of the earlier offline call.
2. The default deadline is 30 minutes and the maximum is 12 hours. Set expiresInSeconds (60 to 43200), or waitUntil as a duration such as "3 hours", a clock time such as "3:30pm" with an IANA timeZone, or an ISO time. The job runs as soon as the computer is online and is discarded at the deadline. The reply's waitUntil states the interpreted deadline. Computer access and direct-token expiry can shorten it. Queueing never extends computer access.
3. The immediate reply includes status: "queued", computerState, jobId and expiresAt. This confirms acceptance. Inform the person that the work is waiting.
4. Call job_wait once with { jobId }. The service waits and returns the final result. Use reply.result on completion and inspect shell exit codes. Stop on completed, failed, cancelled, expired or outcome_unknown. Never repeatedly call job_status to keep a model busy while waiting.
5. Use job_cancel to stop pending work. cancelled: true prevents dispatch. cancelled: false means it was dispatched or terminal and cannot be stopped by cancellation. Aborting a wait leaves the job queued.

job_wait supports MCP task augmentation. A task-capable host can receive a task ID immediately, manage the wait outside model turns, and retrieve the result through tasks/result. Task status and cancellation are authorized by the same job ownership checks. Without task support, the tool waits in its current HTTP call. Host timeouts can close that call; resume waiting with the same job ID rather than submitting again. Waking a closed agent thread requires integration in the host app. A hosted MCP server alone cannot start a new model turn in another app.

If a submission reply is lost, inspect the saved request ID with job_status. Duplicate IDs reject execution without replaying a result. For outcome_unknown, inspect activity or resulting state before deciding what to do.

The helper reconnect wakes the service's queue. Dispatch rechecks permission, folder policy, revocation and the original computer-access deadline. OAuth jobs follow the saved MCP connection across credential renewal; hourly credential expiry does not discard accepted work. Direct-token jobs require that individual token to remain valid. A reconnect never extends a job's deadline. Known undelivered calls can wait again; uncertain sends never retry automatically.

Queued transfer calls still depend on their transfer's existing state and expiry. Queueing a chunk, import or status call cannot recreate expired transfer state. Bulk work uses the public origin saved at submission and the ordinary bulk authorization path, rather than forwarding public bulk arguments directly to the helper.

Arguments and results are capped at 1.5 MB of encoded JSON each. Oversized results report job_result_too_large after the operation may have run. Results remain until one hour after the job deadline. Queued and dispatched jobs count toward 32 jobs per computer and 1,000 globally. Retained completed, cancelled, failed and expired jobs do not consume active queue capacity. A separate storage budget of 64 MiB per computer and 256 MiB globally includes reserved result space; job_storage_full means retained results must expire before more work can be accepted. D1 stores these arguments and results.

REST uses POST https://tunnel.masti.lol/api/jobs with the queue body and an agent bearer token. /api/jobs/wait waits up to 55 seconds for a result; a client library can repeat that wait without involving a model. /api/jobs/status inspects once, and /api/jobs/cancel cancels, each accepting { "jobId": "..." }.

The SDK exposes remote.queue(deviceId, operation, args, { requestId, expiresInSeconds }), remote.waitJob(jobId, { signal, onUpdate }), remote.job and remote.cancelJob. waitJob uses the server wait endpoint. Pi exposes ezremote_queue with the same optional deadline and ezremote_job, which waits by default. Set wait: false to inspect once. Native Pi tools still run on the Pi host when device is omitted. Configure a scoped agent token through isolated Pi settings; store only the activated agent token.

Keep a Terminal session

Use shell.start for commands that may exceed 30 seconds, servers, prompts and REPLs. Save its sessionId. Call shell.read with that ID, a byte cursor starting at 0 and optional waitMs up to 20000. Save the returned cursor for the next read unchanged. bytesDropped > 0 means output was lost from the buffer. maxBytes defaults to 65536 and accepts 4–524288 bytes. The cursor advances only over returned bytes; more: true means output remains. Reads preserve UTF-8 character boundaries. running and code say whether the process has exited. Send a line with shell.write, including its newline. Use shell.status, shell.list and shell.kill to inspect or stop work.

Each connection has eight sessions, each with a 1 MB output buffer. Sessions end at connection expiry or after two hours without an agent read, write or status call. Set idleMinutes on shell.start to 1–1440 minutes; the default is 120. Connection expiry always wins. Exited output is retained for five minutes. Background jobs (cmd &) end when the session's shell exits; keep the shell in the foreground, for example with wait, to keep them running. Sessions run through the same Terminal sandbox as shell.exec. Pipes support interactive line input, but programs requiring a TTY are unsupported. The person can inspect and kill sessions from the helper tray or ezremote sessions list and ezremote sessions kill ID.

Read, list and search with coverage

files.read without limit returns the whole file up to 1 MB. Before writing a file back, check that its read status is complete. For large files, page with a zero-based line offset and a limit up to 1000, or tail: true. Pass the opaque cursor to continue. files.list accepts depth up to 20 and limit up to 1000. files.stat returns size, type and modification time. files.search accepts a literal query, mode: "names" or "content", depth, limit, timeoutMs up to 3000 and maxBytes up to 16000000. Content search returns the first matching line per file. Continue with cursor and the same query options.

All these results include status, skipped and scannedBytes. complete covers the requested range; partial has another page or skipped files; truncated hit a size or entry budget; timed_out hit the time budget. Follow a cursor when one is returned and retain skipped-file reports across pages. Empty results establish absence only when status is complete. Binary files, files over the search byte budget, inaccessible paths and symlink directories are reported in skipped. Search scans at most 1 MB per file. Raise the budget or use paged reads to inspect an oversized file. Filesystem edits during pagination can change results.

Resolve an uncertain outcome

Never retry outcome_unknown blindly. Save the request ID and call MCP resolve_operation with deviceId and requestId, or POST those fields to https://tunnel.masti.lol/api/operations/resolve. The SDK provides remote.resolve(deviceId, requestId). Resolution never runs the operation again.

running describes a mutating request the current helper has admitted. Read-only calls are not journaled and resolve to unknown; they are safe to retry. refused_expired means it did not start because its deadline passed. finished includes the saved reply. A resultTruncated reply retains the success or failure but omits an oversized result. unknown means the helper is offline, has no retained record, or restarted while the outcome was uncertain. Inspect activity and resulting state before deciding what to do next. A fresh ID is new work, not a safe retry. Results remain available for at most 24 hours, 1,024 requests or 16 MB, whichever limit is reached first, and each reply is capped at 64 KB.

Synchronous calls accept deadlineInMs from 1000 to 55000, default 30000. This is an admission deadline, not cancellation of a running command. Use sessions for long commands and explicit offline jobs when work should wait for a computer.