Skip to content
Back to search

tinyagentaccess

Open-source, self-hostable Rust MCP server for agent computer use (macOS, Linux, Windows), modeled on AWS WorkSpaces AgentAccess

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 18 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/letsopen-ai/tinyagentaccess with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/letsopen-ai/tinyagentaccess'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/letsopen-ai--tinyagentaccess/badge.svg)](/listings/letsopen-ai--tinyagentaccess)

HTML

<a href="/listings/letsopen-ai--tinyagentaccess"><img src="/api/listings/letsopen-ai--tinyagentaccess/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 195 lines
  1. # tinyAgentAccess
  2. [![CI](https://github.com/letsopen-ai/tinyagentaccess/actions/workflows/ci.yml/badge.svg)](https://github.com/letsopen-ai/tinyagentaccess/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  4. An open-source, self-hostable, local-first Rust rebuild of the Amazon WorkSpaces for AI agents MCP server. AWS-compatible native tool names, running on your own computer, with no AWS dependency.
  5. **v0.1.0:** desktop capture/input, sequences, forwarding, dialect adapters, local replay and human Stop.
  6. **Security: no authentication. Binds to localhost by default. Do not expose this server to a network or the public internet. Wildcard binds are rejected; concrete non-loopback binds warn. Host/Origin checks are not authentication.** Security: see [SECURITY.md](SECURITY.md).
  7. **Not affiliated:** tinyAgentAccess is an independent project, not affiliated with,
  8. endorsed by, or associated with Amazon Web Services or Amazon. "Amazon", "AWS",
  9. "Amazon WorkSpaces", and related names are trademarks of Amazon.com, Inc. or its
  10. affiliates. Compatibility is a local reimplementation from public documentation
  11. and the MIT-0 sample; this is not an official AWS product.
  12. ### Feature and parity status
  13. | Area | Status |
  14. | --- | --- |
  15. | Native tools | Local capture/input, session, wait, and sequences; AWS-only tools dropped (see [design](docs/design.md)) |
  16. | Linux X11 | Verified end to end on Xvfb (CI / lab); real desktop sessions need separate validation |
  17. | Linux Wayland | Experimental; unverified on real GNOME/KDE sessions |
  18. | macOS | ScreenCaptureKit verified on one non-Retina host |
  19. | Windows | Compiled / CI; GUI untested |
  20. | Forwarding | Local stdio MCP tools |
  21. | Dialects | Best-effort, **PROVISIONAL**, unverified against AWS |
  22. | Local replay / observer | **TINY-PROPOSAL**; local artifacts and human Stop |
  23. | Authentication | Not implemented |
  24. ### Current limitations / known issues
  25. - Tk and some window client areas may capture blank on macOS while the title bar remains visible.
  26. - Retina, multi-monitor, denied-permission, and real GNOME/KDE Wayland behavior are not fully verified.
  27. - Dialect schemas and forwarded-tool behavior with an unknown interface header are provisional.
  28. - AWS mid-sequence Stop semantics are unknown; local sequences check Stop between steps.
  29. ### Release archives
  30. Releases provide Linux/macOS `.tar.gz` archives and a Windows x86_64 MSVC `.zip`.
  31. Each includes `THIRD_PARTY_LICENSES.html`, generated by cargo-about with full
  32. dependency license texts. Verify the download against `SHA256SUMS` and its
  33. Sigstore bundle using cosign; archives and the standalone license bundle also
  34. have `.sigstore.json` signatures. For example:
  35. ```sh
  36. cosign verify-blob --bundle SHA256SUMS.sigstore.json \
  37. --certificate-identity "https://github.com/letsopen-ai/tinyagentaccess/.github/workflows/release.yml@refs/tags/v0.1.0" \
  38. --certificate-oidc-issuer https://token.actions.githubusercontent.com SHA256SUMS
  39. sha256sum --ignore-missing -c SHA256SUMS
  40. ```
  41. On macOS, use `shasum -a 256 --ignore-missing -c SHA256SUMS`. In PowerShell,
  42. use `Get-FileHash .\tinyagentaccess-x86_64-pc-windows-msvc.zip -Algorithm SHA256`
  43. and compare the hash with `SHA256SUMS`. Windows binaries are not Authenticode-signed
  44. (SmartScreen may warn); Windows support is compiled / CI checked, with GUI untested.
  45. ### Build and run from source
  46. Install Rust 1.88+ (edition 2021), clone this repository, and run from its root.
  47. See [permissions](docs/permissions.md) and [testing](docs/testing.md) for OS setup.
  48. ```sh
  49. cargo run -p tinyagentaccess -- serve
  50. # Optional: --config config.example.toml --bind 127.0.0.1:8765
  51. cargo run -p tinyagentaccess -- print-config
  52. ```
  53. Stateful curl smoke test (requires Python 3 to extract the session header):
  54. ```sh
  55. curl -sS -D /tmp/taa-headers -H 'Content-Type: application/json' \
  56. -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}' \
  57. http://127.0.0.1:8765/mcp
  58. TAA_SESSION=$(python3 -c 'print(next(x.split(":",1)[1].strip() for x in open("/tmp/taa-headers") if x.lower().startswith("mcp-session-id:")))')
  59. curl -sS -H "Mcp-Session-Id: $TAA_SESSION" -H 'MCP-Protocol-Version: 2025-11-25' \
  60. -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","method":"notifications/initialized"}' http://127.0.0.1:8765/mcp
  61. curl -sS -H "Mcp-Session-Id: $TAA_SESSION" -H 'MCP-Protocol-Version: 2025-11-25' \
  62. -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' http://127.0.0.1:8765/mcp
  63. curl -sS -H "Mcp-Session-Id: $TAA_SESSION" -H 'MCP-Protocol-Version: 2025-11-25' \
  64. -H 'Content-Type: application/json' -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"agentaccess___wait","arguments":{"duration":0.001}}}' http://127.0.0.1:8765/mcp
  65. curl -sS -i -X DELETE -H "Mcp-Session-Id: $TAA_SESSION" -H 'MCP-Protocol-Version: 2025-11-25' http://127.0.0.1:8765/mcp
  66. ```
  67. Run SDK interop against the running server by installing `mcp==2.1.1` in a virtual environment and running `python scripts/interop_python_sdk.py --url http://127.0.0.1:8765/mcp`. It tests both legacy/stateful and 2026-07-28/stateless modes.
  68. Desktop requirements:
  69. - **X11:** run inside the graphical session with `DISPLAY` and Xauthority access. Uses pure Rust x11rb, XTest input, RandR primary monitor and GetImage capture. No Xlib/libxcb development packages.
  70. - **Wayland (experimental):** install xdg-desktop-portal plus the GNOME/KDE backend. Approve Screenshot and RemoteDesktop access, selecting your primary monitor. Persistent consent tokens are stored with mode 0600 under `$XDG_STATE_HOME/tinyagentaccess/portal-restore-token` (default `~/.local/state/...`). Capture uses the Screenshot portal, without libpipewire; use a **single-monitor session** for now because that API may return the entire desktop. Known Screenshot/RemoteDesktop ratio mismatches fail before pointer injection; equal ratios cannot prove monitor identity. The portal cannot force primary-monitor capture or reliably honor `include_cursor=false`/`true`. Portal Unicode delivery still requires compositor testing. Consent waits are bounded to 60 seconds; cached session info stays available.
  71. - **macOS:** grant Screen Recording and Accessibility to the terminal/app launching the server, then restart it. ScreenCaptureKit screenshots on macOS 14+ and CGEvent input are intended to preserve Retina pixel/point mapping; Retina behavior is not fully verified. The binary requires macOS 12.3+; when the screenshot class is absent, capture uses a dynamically resolved legacy CoreGraphics API if available. tinyagentaccess never requests a permission prompt; macOS 15+ may show its own periodic Screen Recording confirmation.
  72. - **Windows:** GDI primary-display capture and DPI-aware SendInput. Use an unlocked interactive desktop. UAC/secure desktop and higher-integrity windows cannot be controlled. Code is cross-compiled here; GUI validation is still needed.
  73. M2 targets the **primary display only** (Wayland currently requires one display). Default images are 1280×720, aspect-preserving with centered black bars; clicks in bars clamp to the display edge. Native mode returns physical capture dimensions. All desktop operations run in blocking workers. PNG and JPEG are supported. See [keys](docs/keys.md), [permissions](docs/permissions.md), [testing](docs/testing.md) and the [design limitations](docs/design.md).
  74. Linux auto selection prefers Wayland whenever `WAYLAND_DISPLAY` or `XDG_SESSION_TYPE=wayland` is present, even when `DISPLAY` also exists: XWayland XTest cannot control native Wayland windows. Override with `[platform] linux_backend = "auto" | "wayland" | "x11"`. With no graphical session the server starts and desktop calls return an actionable error. No TLS or C cross-compiler is required for Windows GNU type-checks.
  75. Workspace: `crates/tinyagentaccess` (CLI), `crates/taa-mcp` (HTTP/session lifecycle), `crates/taa-tools` (config, registry, validation, dispatch), `crates/taa-platform` (typed desktop boundary, shared images/keys, OS backends and an opt-in `test-support` recording mock).
  76. See [verified AWS parity facts](docs/aws-parity.md), [design and compatibility decisions](docs/design.md), and [example config](config.example.toml). Validate with `cargo fmt --all -- --check`, `cargo clippy --workspace --all-targets -- -D warnings`, and `cargo test --workspace`.
  77. See [Contributing](CONTRIBUTING.md), [Code of Conduct](CODE_OF_CONDUCT.md),
  78. [Security](SECURITY.md), [Changelog](CHANGELOG.md), and
  79. [third-party notices](THIRD_PARTY_NOTICES.md).
  80. [MIT](LICENSE) © 2026 Chen Nie.
  81. Wildcard binds (`0.0.0.0` / `::`) are rejected because this server has no authentication. Use the loopback default or an explicit concrete IP; non-loopback binds emit a no-auth warning and only that IP or loopback Host values are accepted.
  82. Local screenshot saving is optional and disabled by default:
  83. ```toml
  84. [screenshots]
  85. save_dir = "" # disabled; otherwise set an absolute private directory
  86. ```
  87. Returned standalone and sequence terminal images are saved under `agentaccess/screenshots/year=YYYY/month=MM/day=DD/{session-id}/` using UTC epoch-millisecond filenames and the real PNG/JPEG extension. Unix directories/files use 0700/0600 when created; Windows inherits directory ACLs. Save failures warn on stderr and leave tool results intact. Relative save paths are rejected. No cloud upload occurs.
  88. ### MCP tool forwarding
  89. Set `[agent_access] forward_mcp_tools = true` and optionally set
  90. `[forwarding] config_path = "/absolute/path/redirection.json"`. The redirection file
  91. must be UTF-8 without a BOM:
  92. ```json
  93. {"mcpServers":{"example":{"command":"/absolute/path/mcp-server","args":["--stdio"]}}}
  94. ```
  95. Only stdio is supported. Children inherit the server environment; `env`, `cwd` and
  96. other unknown keys are ignored with warnings. Tools appear as
  97. `forwarded___example___<tool>`. Lists and calls have a five-second timeout. Each MCP
  98. session owns its children and closes them on session expiry or closure. Forwarding-only
  99. operation (`computer_vision = false`, `computer_input = false`, forwarding enabled)
  100. is supported. Empty config_path uses `/etc/dcv/mcp_server_redirection_config.json`
  101. on Linux, `C:\ProgramData\NICE\dcv\mcp_server_redirection_config.json` on Windows,
  102. and the provisional `/Library/Application Support/tinyagentaccess/mcp_server_redirection_config.json`
  103. on macOS. See [design decisions](docs/design.md#mcp-tool-forwarding-m4).
  104. Milestone 5 adds computer-use dialects selected per request with
  105. `x-amzn-agentaccess-computer-use-interface-id`: `ANTHROPIC_COMPUTER_20250124`,
  106. `ANTHROPIC_COMPUTER_20251124`, `ANTHROPIC_COMPUTER_TOOLSET_20260801`,
  107. `OPENAI_COMPUTER_V1`, and `GOOGLE_COMPUTER_USE_3X_DESKTOP_V1`.
  108. Send it on both tools/list and every tools/call. Omitted/empty selects native tools;
  109. unknown values return JSON-RPC -32602. Dialects are **best-effort, unverified vs AWS**;
  110. all schemas are **PROVISIONAL vendor-derived, not AWS-confirmed**. Only standard
  111. desktop tools are replaced; session, wait, sequence and forwarded tools stay available.
  112. See the [local conversion choices](docs/design.md#m5-computer-use-dialect-adapters).
  113. ### Local replay and human control (M7)
  114. ```toml
  115. [replay]
  116. enabled = true
  117. save_dir = "/absolute/private/replay"
  118. # max_bytes_per_session = 104857600 # optional frame-storage budget; default unlimited
  119. [agent_access]
  120. user_control_mode = "view_stop" # disabled (default) | view_only | view_stop
  121. ```
  122. Replay captures a whole-screen image immediately before each desktop action, including
  123. translated calls and individual sequence steps, using the configured PNG/JPEG renderer
  124. and default cursor setting. Responses are appended after completion. Wait, session
  125. metadata and forwarded calls have metadata only. Frames and append-only `events.jsonl`
  126. live under `agentaccess/replay/year=YYYY/month=MM/day=DD/{mcp-session-id}/`.
  127. Closure (tool, DELETE, idle expiry or Stop) writes an escaped local `index.html`.
  128. These are **TINY-PROPOSAL local artifacts, not an AWS/Bedrock evidence report**;
  129. there is no video, transcript, S3, KMS, or automatic retention deletion.
  130. Replay can contain sensitive screen/text/tool data; enable only in a private directory
  131. and remove it yourself. Unix creation modes are 0700/0600, Windows inherits ACLs;
  132. symlink sink directories and existing output files are refused. Failures warn without
  133. changing the tool result. The optional replay byte budget stops frame storage with one warning; metadata and the index continue and may exceed the budget. Opaque metadata is capped (see [M7 choices](docs/design.md#m7-local-replay-and-human-control)).
  134. Open `http://127.0.0.1:8765/observe` on the same origin as the server. `view_only`
  135. shows session selection and fresh screenshots; `view_stop` also shows Stop. `disabled`
  136. returns 404 for observer routes. All local sessions share one desktop; selection
  137. chooses which session to observe or close, not a separate OS desktop. Polling uses
  138. the normal capture path and may require OS consent. Stop releases held input, ends forwarding, and
  139. marks the session stopping immediately and closes it after the admitted action finishes. Sequences check Stop between steps (PROVISIONAL; AWS mid-action semantics unknown). Observation does not reset the idle timer. Queued calls
  140. then fail like calls after normal closure. **TINY-PROPOSAL:** Stop closes only the
  141. targeted MCP session; it is not a lockout and does not block new sessions. Legacy
  142. transport sessions then get HTTP 404; the [MCP Streamable HTTP spec](https://modelcontextprotocol.io/specification/2025-11-25/basic/transports)
  143. requires clients to start a new session after a 404 for a request carrying
  144. `Mcp-Session-Id`, so a client may re-initialize and continue without the agent
  145. noticing. Modern-dialect calls with the stopped `mcpSessionId` return an
  146. `Unknown mcpSessionId` tool error, and the agent may continue by calling again with
  147. `mcpSessionId: "NEW"`. To keep an agent off the desktop, stop the agent/MCP client
  148. or the tinyAgentAccess server. `user_control_mode` controls observation and Stop
  149. availability, not agent access.
  150. No `client_disconnected` notification is emitted: its AWS wire form is unknown.
  151. The observer is an **unauthenticated local substitute, not AWS DCV**. Keep the bind
  152. on loopback until authentication exists. Host/Origin checks and same-origin Stop
  153. requests reduce browser abuse; they do not authenticate local users.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.