How ezremote works
For people and agents who want the model behind the setup steps, and the limits.
ezremote lets an AI agent use a person's computer. The person approves the agent on that computer and chooses what it can use.
Five words
| Word | Meaning |
|---|---|
| Computer | The person's machine. |
| Helper | The app installed on the computer. It runs as that OS user and connects out to ezremote, so the computer opens no port. |
| Agent | The AI asking to use the computer: Claude, Codex, Pi or a script. |
| Connection | One agent joined to one computer, approved by a person on that computer. Permissions and folder rules belong to it, so one agent can have different access on two computers. |
| Permission | Files, Terminal, Browser or MCP servers. Each is a switch with finer controls. |
A person can have several computers and agents. Connections come in two kinds:
| Temporary | Lasting | |
|---|---|---|
| Account | Not needed | Needed |
| Ends | Within 24 hours of the request | When someone revokes it |
| Terminal | Sandboxed only, none on Windows | Sandboxed, or full access by choice |
| MCP servers | Never | Off until the person turns them on |
| Agent credential | The agent's own secret, switched on after approval | OAuth or an agent token |
Saving a temporary connection to an account makes it lasting with the same permissions.
Life of a connection
- Requested. The agent gets a setup link from
connect_computerorPOST /api/connect/request. - Approved. The person opens the link on the computer, chooses permissions, runs the setup command and approves in the terminal. Setup installs the helper if needed.
- Active. The service checks each call's credential and connection, then forwards it to the helper. The helper checks permissions again before it runs anything, as the computer's user.
- Ended. The person revokes it or it expires. New calls fail, though a command already started may finish.
While the helper is offline, calls return device_offline and nothing runs. The agent can queue work for when the computer returns. The agent's own built-in tools never touch the computer; they act where the agent runs. The service at https://tunnel.masti.lol relays calls and can read them (what it sees).
Limits
This table is the one home for these numbers.
| What | Limit |
|---|---|
| Setup link and pairing code | 10 minutes |
| Temporary access | Up to 24 hours from the request. durationSeconds accepts 60 to 86,400. |
| Saving a temporary connection | Until 24 hours after its access ends |
| Temporary requests | 10 per hour from one address, 500 per hour in total |
| Agent token | 7 days at most. Dashboard tokens default to 24 hours. |
| OAuth access credential | 1 hour, refreshed by the client |
deadlineInMs | 30 seconds by default, 1 to 55 seconds |
shell_exec timeoutMs | 1 to 55 seconds |
| Text read, write or edit | 1 MB |
files_read page | 1,000 lines |
files_list, files_search | Depth 20, 1,000 entries per page |
files_search budget | 3 seconds, 16,000,000 bytes, 1 MB scanned per file |
| Small transfer chunk | 192 KB before base64 |
| Large transfer | 10 GiB per file. The job lasts 1 hour, a download link 5 minutes. |
| Terminal sessions | 8 running per connection, 1 MB output buffer each |
Session idle expiry, idleMinutes | 120 minutes by default, 1 to 1,440 |
shell_read | maxBytes 64 KiB by default, up to 512 KiB. waitMs up to 20 seconds. |
| Finished sessions | Readable for 5 minutes. The helper keeps the last 32. |
| Queued job deadline | 30 minutes by default, 12 hours at most, never past the connection's end |
| Queued job arguments, result | 1.5 MB each. Results stay 1 hour past the deadline. |
| Active queued jobs | 32 per computer, 1,000 in total |
| Queued job storage | 64 MiB per computer, 256 MiB in total |
/api/jobs/wait | 55 seconds per call |
| Helper result journal | 24 hours, 1,024 requests or 16 MB, whichever comes first. 64 KB per reply. |
operations | The last 100 records |
| Browser import | 50,000 history entries, 50,000 bookmarks |