The best way to control Claude Code, Codex and more from any computer or phone

main
md 171 lines 10.2 KB
Rendered Raw
1 # Devices
2
3 The Device panel shows a live iOS Simulator or Android Emulator next to a
4 thread, so you can watch an agent verify mobile work and tap the device
5 yourself. Agents get the same device through `device_*` tools and the
6 `agent-device` command line, which T3 Code sets up for them.
7
8 ## Open a device
9
10 Open the right panel in a project thread and choose **Device**. On first use,
11 the panel walks through three steps: starting the device hub, checking iOS and
12 Android support, and choosing whether agents may control devices. Opening the
13 panel alone does not download or start anything. If the hub is already
14 installed, the setup screen says so and reuses it.
15
16 Choose a running device to watch it, or choose **Start** next to a stopped
17 device to boot it. The panel shows when you or an agent starts a device.
18 Each device opens in its own tab. Use **+ → Device** to open another, and
19 double-click a tab name or choose **Rename** from its context menu to rename it.
20 Only the visible tab streams video; switching tabs keeps both devices running.
21 Choose **Float device over chat** in the toolbar to keep watching and tapping the
22 device in a small window while the right panel shows something else; drag the
23 window by its handle, resize it from any edge, and use **Open in right panel**
24 to bring it back.
25 Turn off **Use devices** in **Settings → Devices** to stop the
26 helper processes; simulators and emulators keep running until you power them
27 off.
28
29 Simulators run on the machine that hosts the environment server. iOS needs
30 macOS with Xcode. Android needs the SDK Platform-Tools, Android Emulator,
31 and Command-line Tools (latest), plus a virtual device created in Android
32 Studio's Device Manager. T3 Code detects standard SDK locations; set
33 `ANDROID_HOME` for a custom location. The panel explains missing dependencies.
34 After installing SDK tools, restart the environment server and refresh devices.
35
36 Android emulator video also needs `ffmpeg` with the libx264 encoder on the device
37 host's PATH, or an executable selected by `SERVE_EMU_FFMPEG` on that host. If
38 opening an emulator reports an ffmpeg problem, install or fix the executable
39 and retry opening it. After changing PATH or `SERVE_EMU_FFMPEG`, restart the
40 environment server for local devices, or turn device support off and on for SSH
41 devices, so the running tools inherit the new environment. Physical Android
42 devices and iOS do not need ffmpeg.
43
44 The screen is interactive: click and drag to touch, type while the screen is
45 focused, and use the toolbar for Home, Back, and Recents on Android, rotate on
46 iOS, and power off. Close the tab to stop watching; the device keeps running
47 unless you power it off. Closed tabs stay closed after a reload. To watch the
48 device again, choose it from **+ → Device**.
49
50 Choose **3D view** to inspect supported devices while the live screen stays
51 interactive. On iPhone Duo, use the fold and stance controls to change its
52 physical pose, or pinch over the device to adjust the hinge. Turning the model
53 to the other screen switches the live display and touch input to that screen.
54 **Restore 3D view** returns the device to a screen-facing position.
55 On supported Android foldables, use **Fold device** and **Unfold device** beside
56 the screen to change its posture in either view.
57
58 ## Tools
59
60 The toolbar's **Tools** button opens a drawer for the open device. It shows the
61 foreground app, and lets you switch light and dark mode, change text size,
62 flip accessibility settings, overlay the accessibility element frames on the
63 screen, set a fake location, and grant or revoke app permissions. iOS also
64 exposes Liquid Glass, color filters, VoiceOver, and sending a test push
65 notification; Android adds orientation and toggling the network. The drawer
66 only shows what the platform can do, and every control reflects the value read
67 back from the device after a change.
68
69 ## Agents and devices
70
71 When an agent opens a device, it floats over the chat in web and desktop clients
72 connected to the thread, the same way an agent-driven browser does. Turn off
73 **Auto-show floating preview** in **Settings → Browser** to open a
74 right-panel tab instead. In the mobile app, open the agent's thread and tap the
75 device button above the composer to watch the live screen and control it.
76 On iOS layouts with an inspector, the device opens beside the thread. Maximize
77 it to fill the screen; closing the full-screen view returns to the inspector.
78 If the thread has several devices open, choose one in the viewer. Closing the
79 viewer stops streaming and leaves the device available to the agent. Device
80 activity also appears in the thread timeline.
81
82 Agents drive the device through the `agent-device` command line. T3
83 Code installs and starts it only after **Agents can use devices** is on. iOS
84 taps build a small test runner on first use, which takes a couple of minutes
85 once per server. Restart an existing agent session after granting access so it
86 receives the device CLI environment.
87
88 To keep agents away from simulators, turn off **Agents can use devices** in
89 **Settings → Devices**. This hides the device tools from agents
90 started from then on; your own Device panel is unaffected.
91
92 ## Remote connections
93
94 The device stream goes through the environment server, so it works over the
95 local network, Tailscale, and T3 Connect. Live video needs a secure page
96 (HTTPS or localhost); on a plain-HTTP remote origin iOS falls back to a slower
97 still-image stream and Android cannot show video, except on Expo Simulators.
98
99 ## SSH device hosts
100
101 In Settings → Devices, choose the environments that should use
102 the host and choose **Add source → Machine over SSH**. Enter an SSH alias or `user@host`, with
103 an optional identity file and port. These resolve on the environment server,
104 so use the SSH configuration and keys available there. Password prompts are
105 not supported.
106
107 **Test connection**, in the host's menu, checks SSH, Node, npm, and platform tools without installing
108 anything, with a result for each selected environment. Targets that resolve to
109 the environment’s own machine are skipped, since its devices are already local.
110 The first device listing installs pinned device tools on the host.
111 SSH device hosts currently need macOS or Linux. To use devices on a Windows
112 machine, run T3 Code on that machine and connect to its environment.
113 Node 22.12 or newer and npm must be available to non-interactive SSH commands.
114 T3 checks common Homebrew and Android SDK locations; custom installations need
115 the appropriate PATH and `ANDROID_HOME` or `ANDROID_SDK_ROOT` on the host.
116 Android on an SSH host needs the same SDK tools as a local environment; adb on
117 the PATH alone does not enable it. Android emulator video needs
118 `ffmpeg` with libx264 on that host; physical Android devices use scrcpy and do
119 not need ffmpeg.
120
121 The picker identifies devices by host when several hosts are configured.
122 Connections recover after interruptions. Removing a host closes its device
123 sessions and stops its T3 helpers when reachable; simulators keep running.
124
125 T3 provides discovery, streaming, and control. Arrange app builds,
126 installation, and connectivity to development servers such as Metro separately.
127 A simulator on another machine cannot reach Metro through your environment's
128 localhost without forwarding or another reachable address.
129
130 ## Simlock hosts (alpha)
131
132 [Simlock](https://incubator.callstack.com/simlock/) pools iOS simulators and
133 Android emulators across machines. If you run a Simlock gateway, T3 can lease
134 devices from it. Simlock is new and unreleased, so this integration is an
135 alpha: it may change or stop working with a newer Simlock. T3 does not install
136 or manage Simlock; set up the gateway and its workers yourself. It needs a
137 gateway and workers built from Simlock's `main` at
138 [6316e10](https://github.com/callstackincubator/simlock/commit/6316e10) or
139 later, the first with a lease holder's screen and input.
140
141 Turn on **Settings → Labs → Simlock device hosts (alpha)** and **Use devices**
142 in Settings → Devices, then choose **Add source → Simlock pool** with an **agent token**
143 (`simlock --gateway token create --role agent`). Give each T3 server its own
144 token: Simlock counts every lease made with one token against the same
145 requester, and allows one at a time unless the gateway's
146 `lease.maxPerRequester` is raised to the host's **Devices at once**. The token
147 leases devices and reaches only its own leases, but commands on a leased device
148 run on its worker, so treat it like shell access to your workers. T3 sends it
149 with every request, so use an HTTPS gateway URL, or plain HTTP only over an
150 encrypted network such as Tailscale. The gateway
151 and workers need `capabilities.stream.enabled` and `capabilities.input.enabled`
152 for the live screen and for input.
153
154 The picker lists the models your workers can make. Opening one takes a lease;
155 closing it with **Return device to the pool**, or removing the host, returns it
156 wiped. The panel keeps a watched device leased up to the host's lease limit.
157 You can tap, swipe, type, and press Home, and Back and Recents on Android.
158 Rotation, appearance, text size, device tools, and screenshots are not offered
159 for Simlock devices; agents can still do them through `device_open`. On iOS 27
160 simulators, typing on your keyboard does nothing; tap the on-screen keyboard
161 instead. Workers must run the same agent-device
162 version as T3 (see Device tool updates), and agent-device accepts app installs
163 for a lease only from the folder it was opened from, which `device_open`
164 names. A device cannot reach development servers on your machine through
165 localhost; use an address its worker can reach.
166
167 ## Device tool updates
168
169 The connected T3 server manages the device hub and agent tools on its own machine and configured SSH hosts. Required versions install automatically the next time those tools are used. In Settings → Devices, select a version and choose **Check versions** to read installed versions without installing tools or starting devices.
170
171 To receive newer tool versions on a remote environment, update that environment's T3 server. Updating only the browser or mobile app does not update the remote server. An offline host keeps its installed files, but an update needs network access before device support can start; T3 does not fall back to an older version. Reconnect the host and use Retry if installation fails. Existing device and agent-access settings are preserved.