tinyios

---

tinyios is cross platform software to talk to ios devices over usb or wifi. It mimics a small set of features that can be done via xcode, developer tools and system settings on a mac.

It exposes itself as a HTTP server so it can be accessed from anywhere. It is also stateless and rootless which makes it easy to run as an ephemeral container.

tinyios depends on usbmuxd installed on the host machine to manage device pairing and device communication through usb or wifi. You will also need to make usbmuxd on the host available inside the container.

Purpose

The main purpose of tinyios is to set up ios devices and then talk to them via Appium WebDriver commands. Once a device is set up, drive it through the WDA passthrough — everything under /{udid}/wda/cmd/ is forwarded straight to WebDriverAgent on the device.

---

Installation

WSL

1. Forward device to WSL

2. Install dependencies

   To use tinyios on Linux or WSL you need to install usbmuxd to handle device pairing and device communication. You can run these commands to install or update existing usbmuxd to the latest version

   git clone https://github.com/libimobiledevice/usbmuxd.git
   cd usbmuxd
   ./autogen.sh
   make
   sudo make install

   You will also need socat to make usbmuxd available from the host to container

   sudo apt install socat
   sudo socat TCP-LISTEN:27015,reuseaddr,fork UNIX-CONNECT:/var/run/usbmuxd

3. Run latest container image on port 8080

   docker run --rm \
     -p 8080:8080 \
     -e USBMUXD_SOCKET_ADDRESS=host.docker.internal:27015 \
     albinstman/tinyios

Linux

1. Install dependencies

   To use tinyios on Linux or WSL you need to install usbmuxd to handle device pairing and device communication. You can run these commands to install or update existing usbmuxd to the latest version

   git clone https://github.com/libimobiledevice/usbmuxd.git
   cd usbmuxd
   ./autogen.sh
   make
   sudo make install

   You will also need socat to make usbmuxd available from the host to container

   sudo apt install socat
   sudo socat TCP-LISTEN:27015,reuseaddr,fork UNIX-CONNECT:/var/run/usbmuxd

2. Run latest container image on port 8080

   docker run --rm \
     -p 8080:8080 \
     -e USBMUXD_SOCKET_ADDRESS=host.docker.internal:27015 \
     albinstman/tinyios

Mac

1. Make usbmuxd available for container

   brew install socat
   socat TCP-LISTEN:27015,reuseaddr,fork UNIX-CONNECT:/var/run/usbmuxd

2. Run latest container image on port 8080

   docker run --rm \
     -p 8080:8080 \
     -e USBMUXD_SOCKET_ADDRESS=host.docker.internal:27015 \
     albinstman/tinyios

---

Documentation

The API Reference below is generated from the annotations on the handlers in main.go. After changing or adding an endpoint, regenerate it with:

make docs

---

API Reference

Base URL http://localhost:8080 — every response is JSON.

Device-scoped routes take the target device's udid as the first path segment. List connected devices with GET /devices to find it.

Overview

	Method	Endpoint	Description
Device
	GET	/devices	List devices
	POST	/{udid}/erase	Erase device
	GET	/{udid}/processes	List processes
	POST	/{udid}/reboot	Reboot device
Pairing
	POST	/{udid}/pair/enable	Enable pairing
	GET	/{udid}/paired	Check pairing status
Activation
	POST	/{udid}/activate/enable	Enable activation
	GET	/{udid}/activated	Check activation status
Supervision
	POST	/{udid}/supervise/enable	Enable supervision
	GET	/{udid}/supervised	Check supervision status
Developer
	GET	/{udid}/devmode	Check developer mode status
	POST	/{udid}/devmode/enable	Enable developer mode
	GET	/{udid}/image	Check developer disk image status
	POST	/{udid}/image/enable	Mount developer disk image
Profiles
	POST	/{udid}/profiles/add	Add profile
	POST	/{udid}/profiles/http	Set global HTTP proxy
	GET	/{udid}/profiles/list	List profiles
Apps
	POST	/{udid}/apps/install	Install application
	POST	/{udid}/apps/kill	Kill application
	GET	/{udid}/apps/list	List applications
	POST	/{udid}/apps/run	Run application
WDA
	ANY	/{udid}/wda/cmd/	WebDriverAgent passthrough
	POST	/{udid}/wda/kill	Kill WebDriverAgent
	POST	/{udid}/wda/run	Run WebDriverAgent

Device

GET /devices

Returns a list of all connected iOS devices

curl http://localhost:8080/devices

POST /{udid}/erase

Erases all content and settings from the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/erase

GET /{udid}/processes

Returns a list of running processes on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/processes

POST /{udid}/reboot

Reboots the specified iOS device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/reboot

Pairing

POST /{udid}/pair/enable

Pairs the device using the provided certificate

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/pair/enable

GET /{udid}/paired

Returns whether the device is paired

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/paired

Activation

POST /{udid}/activate/enable

Activates the specified iOS device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/activate/enable

GET /{udid}/activated

Returns whether the device is activated

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/activated

Supervision

POST /{udid}/supervise/enable

Prepares and enables supervision on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/supervise/enable

GET /{udid}/supervised

Returns whether the device is supervised

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/supervised

Developer

GET /{udid}/devmode

Returns whether developer mode is enabled on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/devmode

POST /{udid}/devmode/enable

Enables developer mode on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/devmode/enable

GET /{udid}/image

Returns whether the developer disk image is mounted

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/image

POST /{udid}/image/enable

Mounts the developer disk image on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/image/enable

Profiles

POST /{udid}/profiles/add

Installs a configuration profile on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID
profile	body	ProfileAddRequest	yes	Base64 encoded profile

Body:

{
  "b64profile": "<string>"
}

curl -X POST http://localhost:8080/<udid>/profiles/add \
  -H 'Content-Type: application/json' \
  -d '{"b64profile": "<string>"}'

POST /{udid}/profiles/http

Configures the device to use an HTTP proxy for profile installation

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID
request	body	ProfileHttpRequest	yes	HTTP proxy configuration

Body:

{
  "address": "<string>",
  "port": "<string>"
}

curl -X POST http://localhost:8080/<udid>/profiles/http \
  -H 'Content-Type: application/json' \
  -d '{"address": "<string>", "port": "<string>"}'

GET /{udid}/profiles/list

Returns a list of configuration profiles installed on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/profiles/list

Apps

POST /{udid}/apps/install

Installs an application from a URL on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID
request	body	AppInstallRequest	yes	Application IPA URL

Body:

{
  "url": "<string>"
}

curl -X POST http://localhost:8080/<udid>/apps/install \
  -H 'Content-Type: application/json' \
  -d '{"url": "<string>"}'

POST /{udid}/apps/kill

Terminates a running application by process ID

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID
pid	form	string	yes	Process ID

curl -X POST http://localhost:8080/<udid>/apps/kill -d "pid=<pid>"

GET /{udid}/apps/list

Returns a list of applications installed on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/apps/list

POST /{udid}/apps/run

Launches an application on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID
bundleid	form	string	yes	Application bundle identifier

curl -X POST http://localhost:8080/<udid>/apps/run -d "bundleid=<bundleid>"

WDA

ANY /{udid}/wda/cmd/

Transparent reverse proxy to the WebDriverAgent HTTP server running on the device. Everything after /wda/cmd is forwarded verbatim to WDA, exposing its full WebDriver/Appium endpoint surface (for example /status, /session, element interactions). Sub-paths are proxied as-is.

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl http://localhost:8080/<udid>/wda/cmd/status

POST /{udid}/wda/kill

Stops WebDriverAgent on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/wda/kill

POST /{udid}/wda/run

Starts WebDriverAgent on the device

Name	In	Type	Required	Description
udid	path	string	yes	Device UDID

curl -X POST http://localhost:8080/<udid>/wda/run