> Index of all guides: https://tunnel.masti.lol/llms.txt. Agents start at https://tunnel.masti.lol/skill.md.

# 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

1. Requested. The agent gets a setup link from `connect_computer` or `POST /api/connect/request`.
2. 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.
3. 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.
4. 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](security.md#what-the-ezremote-service-can-see)).

## 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 |