@kortix/agent-tunnel 0.1.4 → 0.12.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/README.md +65 -0
  2. package/dist/agent-cli.js +4676 -3174
  3. package/dist/client-cli.js +202 -493
  4. package/package.json +24 -29
  5. package/src/agent/agent.ts +67 -17
  6. package/src/agent/capabilities/desktop/cua-driver.ts +284 -0
  7. package/src/agent/capabilities/desktop.ts +100 -167
  8. package/src/agent/capabilities/enabled-registry.ts +24 -0
  9. package/src/agent/capabilities/filesystem.ts +136 -32
  10. package/src/agent/capabilities/index.ts +1 -1
  11. package/src/agent/capabilities/security.test.ts +204 -0
  12. package/src/agent/capabilities/shell.ts +37 -3
  13. package/src/agent/cli-device-auth.test.ts +179 -0
  14. package/src/agent/cli-help.test.ts +25 -0
  15. package/src/agent/cli.ts +475 -38
  16. package/src/agent/config.test.ts +53 -0
  17. package/src/agent/config.ts +169 -7
  18. package/src/agent/index.ts +1 -0
  19. package/src/agent/security/command-validator.ts +4 -2
  20. package/src/agent/security/path-validator.ts +73 -18
  21. package/src/agent/security/permission-guard.test.ts +52 -0
  22. package/src/agent/security/permission-guard.ts +35 -8
  23. package/src/agent/service.test.ts +63 -0
  24. package/src/agent/service.ts +410 -0
  25. package/src/client/cli.test.ts +150 -547
  26. package/src/client/cli.ts +116 -539
  27. package/src/client/index.ts +1 -1
  28. package/src/client/tools.ts +95 -356
  29. package/src/client/tunnel-client.ts +50 -80
  30. package/src/index.ts +7 -1
  31. package/src/node-ws-polyfill.test.ts +18 -0
  32. package/src/node-ws-polyfill.ts +5 -3
  33. package/src/server/heartbeat.ts +13 -6
  34. package/src/server/relay.test.ts +72 -0
  35. package/src/server/relay.ts +50 -9
  36. package/src/server/server.test.ts +33 -0
  37. package/src/server/server.ts +26 -6
  38. package/src/server/ws-handler.test.ts +158 -0
  39. package/src/server/ws-handler.ts +94 -36
  40. package/src/shared/crypto.ts +2 -3
  41. package/src/shared/index.ts +8 -0
  42. package/src/shared/permissions.ts +292 -0
  43. package/src/shared/types.ts +70 -41
  44. package/dist/agent/index.d.ts +0 -140
  45. package/dist/agent/index.js +0 -21
  46. package/dist/agent/index.js.map +0 -1
  47. package/dist/chunk-7N7GSU6K.js +0 -34
  48. package/dist/client/index.d.ts +0 -183
  49. package/dist/client/index.js +0 -8
  50. package/dist/client/index.js.map +0 -1
  51. package/dist/index.d.ts +0 -7
  52. package/dist/index.js +0 -55
  53. package/dist/index.js.map +0 -1
  54. package/dist/server/index.d.ts +0 -89
  55. package/dist/server/index.js +0 -14
  56. package/dist/server/index.js.map +0 -1
  57. package/dist/shared/index.d.ts +0 -10
  58. package/dist/shared/index.js +0 -20
  59. package/dist/shared/index.js.map +0 -1
  60. package/dist/types-Dpwrd8Ai.d.ts +0 -194
  61. package/src/agent/capabilities/desktop/atspi-helper.ts +0 -345
  62. package/src/agent/capabilities/desktop/csharp-helper.ts +0 -914
  63. package/src/agent/capabilities/desktop/linux-driver.ts +0 -368
  64. package/src/agent/capabilities/desktop/macos-driver.ts +0 -601
  65. package/src/agent/capabilities/desktop/swift-helper.ts +0 -736
  66. package/src/agent/capabilities/desktop/types.ts +0 -201
  67. package/src/agent/capabilities/desktop/windows-driver.ts +0 -220
package/README.md ADDED
@@ -0,0 +1,65 @@
1
+ # `@kortix/agent-tunnel`
2
+
3
+ `@kortix/agent-tunnel` connects a local computer to Kortix through an authenticated reverse tunnel.
4
+
5
+ ## Connect once
6
+
7
+ Run the command shown in a **Computer Tunnel** connector profile. Then approve
8
+ the device code in your browser:
9
+
10
+ ```bash
11
+ npx --yes @kortix/agent-tunnel@latest connect \
12
+ --api-url https://api.kortix.com/v1/tunnel
13
+ ```
14
+
15
+ After approval, the interactive flow asks whether it should install a persistent background service. The default answer is yes.
16
+
17
+ ## Run in the background
18
+
19
+ Install the operating-system background service during connection:
20
+
21
+ ```bash
22
+ npx --yes @kortix/agent-tunnel@latest connect \
23
+ --daemon \
24
+ --api-url https://api.kortix.com/v1/tunnel
25
+ ```
26
+
27
+ The service uses LaunchAgent on macOS, a user systemd service on Linux, and Task Scheduler on Windows.
28
+ It starts at login and restarts after failures. It does not change the computer's sleep settings.
29
+
30
+ ## Manage the background service
31
+
32
+ ```bash
33
+ npx --yes @kortix/agent-tunnel@latest service-status
34
+ npx --yes @kortix/agent-tunnel@latest logs
35
+ npx --yes @kortix/agent-tunnel@latest restart
36
+ npx --yes @kortix/agent-tunnel@latest stop
37
+ npx --yes @kortix/agent-tunnel@latest uninstall-service
38
+ ```
39
+
40
+ Credentials are stored in `~/.agent-tunnel/config.json`. Agent Tunnel requires
41
+ the file to be regular, owned by the current user, and mode `0600` on POSIX.
42
+ Protect the operating-system account because this setup token can authenticate
43
+ the machine until you rotate or delete the connection.
44
+
45
+ Remote API URLs must use HTTPS. Plain HTTP is accepted only for `localhost`,
46
+ `127.0.0.1`, and `::1` development endpoints.
47
+
48
+ ## Permission boundaries
49
+
50
+ Kortix checks connector profile assignment, connector grants, connector tool
51
+ policy, and the machine permission before relaying an operation. The local agent
52
+ then checks the machine permission again.
53
+
54
+ The local config is the maximum boundary. A server grant cannot widen configured
55
+ filesystem paths, blocked paths, shell commands, timeouts, file sizes, or desktop
56
+ features. An empty permission scope is unrestricted inside those local ceilings.
57
+ Use scoped permissions and short expiries for sensitive machines.
58
+
59
+ ## Computer Use driver
60
+
61
+ Agent Tunnel never downloads or executes a desktop driver. Install `cua-driver`
62
+ locally before enabling Computer Use. The tunnel uses an existing binary from
63
+ `CUA_DRIVER_BIN`, `~/.local/bin`, `/usr/local/bin`, or `/opt/homebrew/bin`.
64
+ Treat that binary as trusted local code. Agent Tunnel does not verify or update
65
+ it.