Linux shell for iOS



Build Status goto counter fuck counter

A project to get a Linux shell running on iOS, using usermode x86 emulation and syscall translation.

For the current status of the project, check the issues tab, and the commit logs.


This project has a git submodule, make sure to clone with --recurse-submodules or run git submodule update --init after cloning.

You'll need these things to build the project:

  • Python 3
    • Meson (pip3 install meson)
  • Ninja
  • Clang and LLD (on mac, brew install llvm, on linux, sudo apt install clang lld or sudo pacman -S clang lld or whatever)
  • sqlite3 (this is so common it may already be installed on linux and is definitely already installed on mac. if not, do something like sudo apt install libsqlite3-dev)
  • libarchive (brew install libarchive, sudo port install libarchive, sudo apt install libarchive-dev) TODO: bundle this dependency

Build for iOS

Open the project in Xcode, open iSH.xcconfig, and change ROOT_BUNDLE_IDENTIFIER to something unique. You'll also need to update the development team ID in the project (not target!) build settings. Then click Run. There are scripts that should do everything else automatically. If you run into any problems, open an issue and I'll try to help.

Build command line tool for testing

To set up your environment, cd to the project and run meson build to create a build directory in build. Then cd to the build directory and run ninja.

To set up a self-contained Alpine linux filesystem, download the Alpine minirootfs tarball for i386 from the Alpine website and run ./tools/fakefsify, with the minirootfs tarball as the first argument and the name of the output directory as the second argument. Then you can run things inside the Alpine filesystem with ./ish -f alpine /bin/login -f root, assuming the output directory is called alpine. If tools/fakefsify doesn't exist for you in your build directory, that might be because it couldn't find libarchive on your system (see above for ways to install it.)

You can replace ish with tools/ptraceomatic to run the program in a real process and single step and compare the registers at each step. I use it for debugging. Requires 64-bit Linux 4.11 or later.


iSH has several logging channels which can be enabled at build time. By default, all of them are disabled. To enable them:

  • In Xcode: Set the ISH_LOG setting in iSH.xcconfig to a space-separated list of log channels.
  • With Meson (command line tool for testing): Run meson configure -Dlog="<space-separated list of log channels>".

Available channels:

  • strace: The most useful channel, logs the parameters and return value of almost every system call.
  • instr: Logs every instruction executed by the emulator. This slows things down a lot.
  • verbose: Debug logs that don't fit into another category.
  • Grep for DEFAULT_CHANNEL to see if more log channels have been added since this list was updated.

A note on the JIT

Possibly the most interesting thing I wrote as part of iSH is the JIT. It's not actually a JIT since it doesn't target machine code. Instead it generates an array of pointers to functions called gadgets, and each gadget ends with a tailcall to the next function; like the threaded code technique used by some Forth interpreters. The result is a speedup of roughly 3-5x compared to pure emulation.

Unfortunately, I made the decision to write nearly all of the gadgets in assembly language. This was probably a good decision with regards to performance (though I'll never know for sure), but a horrible decision with regards to readability, maintainability, and my sanity. The amount of bullshit I've had to put up with from the compiler/assembler/linker is insane. It's like there's a demon in there that makes sure my code is sufficiently deformed, and if not, makes up stupid reasons why it shouldn't compile. In order to stay sane while writing this code, I've had to ignore best practices in code structure and naming. You'll find macros and variables with such descriptive names as ss and s and a. Assembler macros nested beyond belief. And to top it off, there are almost no comments.

So a warning: Long-term exposure to this code may cause loss of sanity, nightmares about GAS macros and linker errors, or any number of other debilitating side effects. This code is known to the State of California to cause cancer, birth defects, and reproductive harm.

  • Selecting text will copy it into the pasteboard

    Selecting text will copy it into the pasteboard

    In the latest TestFlight build 35, when I just long press text to select it on iSH, it will be copied into the pasteboard even if I don’t tap the “Copy” item.

    How to reproduce it:

    1. Select text
    2. Tap “Paste” item

    I reproduced the issue on

    • 3rd generation 12.9” iPad Pro with iOS 12.1.1
    • iPad Air 2 with iOS 12.1
    • iPhone XS with iOS 12.1.1

    Related to #25

    opened by kkk669 31
  • wget issue

    wget issue

    a random bad bug (at least with commit fd48ae6, f802873, maybe also with c846847, will try with old commit when I have some time)

    sometime wget issue with "wget: read error: Invalid argument" and the same url with curl work fine. seem to be related to network.

    you can try with following url:, this one should retrieve a 41KB file, this one should retrieve a 5KB file sometime only wget for b work, sometime both work, sometime none work no failure at this time with curl

    no repro 
    opened by francoisvignon 25
  • Oh-my-zsh compatibility

    Oh-my-zsh compatibility

    I'm experiencing OMZ compatibility issue on my 2018 iPad Pro with iPadOS 14.5 beta, which doesn’t happen on my iPhone with iOS 14.4.2.

    Situation: The prompt label doesn’t display, no matter it’s local or remote. Syntax highlighting is also buggy. zsh itself and other shells seem all fine.


    opened by stevapple 22
  • I/O ERROR during apk install

    I/O ERROR during apk install

    We're trying to collect diagnostics for an Apple bug report. If this happens to you, please immediately capture a sysdiagnose (press both volume buttons and the power button simultaneously for a few seconds) and send this to me, along with the approximate date and time the issue occurred and the output of dmesg. Thanks! [email protected]

    i get following error . Any idea ?


    opened by F3000 22
  • Race between execve and proc_pid_cmdline_show

    Race between execve and proc_pid_cmdline_show

    See attached image for some context. This is the script I'm running that causes the crash...

    #!/bin/bash tmux new-session -s "My iPad" -d tmux split-window -h tmux split-window -v tmux -2 attach-session -d

    Note that I can manually create the same layout after running tmux manually.

    Screen Shot 2020-12-06 at 4 53 01 PM
    opened by emkey1 22
  • Friendly-shell 'fish' cannot process a local example, but unknown or corrupted style, of file linking/also originated by unknown tool, which ash/bash, could use uninhibited.

    Friendly-shell 'fish' cannot process a local example, but unknown or corrupted style, of file linking/also originated by unknown tool, which ash/bash, could use uninhibited.

    fish seems to work now.

    Originally posted by @tbodt in

    fetch (1/3) Installing bc (1.07.1-r1) (2/3) Installing libpcre2-32 (10.35-r0) (3/3) Installing fish (3.1.2-r0) Executing Executing busybox-1.31.1-r19.trigger 3 errors; 3025 MiB in 687 packages iPhone0 user [email protected] 26_ 4:00PM~(/root)-zsh:which fish /usr/bin/fish iPhone0 user [email protected] 26_ 4:00PM~(/root)-zsh:ldd /usr/bin/fish /lib/ (0xf7f6e000) => /usr/lib/ (0xf7d99000) => /usr/lib/ (0xf7d09000) => /usr/lib/ (0xf7b74000) => /usr/lib/ (0xf7b5b000) => /lib/ (0xf7f6e000) iPhone0 user [email protected] 26_ 4:01PM~(/root)-zsh:

    iPhone0 user [email protected] 26_ 4:06PM~(/root)-zsh:history 1 apk search go 2 apk list go 3 go --help 4 go packages 5 go list 6 go env 7 go get -u 8 dmesg 9 apk list fish 10 apk add fish 11 which fish 12 ldd /usr/bin/fish 13 fish iPhone0 user [email protected] 26_ 4:06PM~(/root)-zsh:fish Welcome to fish, the friendly interactive shell Type help for instructions on how to use fish [email protected] ~# history Failed to execute process '/usr/bin/less'. Reason: exec: unknown error (errno was 13) [email protected] ~ [125]# dmesg [ 0.000000] 496 stub syscall 375

    [email protected] ~ [1]# ls -la /usr/bin/less -rw-rw-rw- 1 root root 12 Jul 20 00:59 /usr/bin/less [email protected] ~# chmod +x /usr/bin/less [email protected] ~# history Failed to execute process '/usr/bin/less'. Reason: exec: unknown error (errno was 8) The file '/usr/bin/less' is marked as an executable but could not be run by the operating system.

    opened by 62f 21
  • kerberos commands return “Bad file descriptor”

    kerberos commands return “Bad file descriptor”

    HI - I’m really looking forward to use ish to access computing resources from my iPad. We use kerberos for security. I did

    apk add krb5

    and copied my krb5.conf file to /etc/krb5.conf.

    I get a Kerberos ticket with kinit. The communication with our kerberos server seems to work, but it ends with an error...

    ipad-132427:~# kinit <removed>
    Password for <removed> 
    kinit: Failed to store credentials: Bad file descriptor (filename: /tmp/krb5cc_0) while getting initial credentials

    There’s an option to kinit that saves credentials to any file, and when I do a file in /root it fails the same way.

    Furthermore, the klist command, which tells me what tickets I have (maybe none) also fails with a similar Bad file descriptor error.

    I imagine the kerberos executables were built in some incompatible way. Any ideas? Let me know how I can help! Thanks, Adam

    opened by lyon-fnal 21
  • Support ngrok error illegal instruction

    Support ngrok error illegal instruction

    opened by professorUnknown 20
  • Feature Request: Allow the Ish app to run in the background.

    Feature Request: Allow the Ish app to run in the background.

    The Ish app should be allowed to run in the background if you leave the app. Sometimes I have to leave the app, and then the in-app processes would stop so allowing the app to run in the background would be great.

    opened by VincentCCandela 20
  • Inform 7 (interactive fiction)

    Inform 7 (interactive fiction)

    Can someone tell me if Inform 7 works on iSH? I tried to install it with script but obviously it didn't work. I manually unzipped the right files, but when I try to compile a sample file, it doesn't work.

    opened by ecstaticax 19
  • network not use

    network not use

    liuende:~# cat /etc/resolv.conf                        nameserver                                 liuende:~# ping                            PING ( 56 data bytes          ping: sendto: Host is unreachable                      liuende:~# apk add openssh                             fetch 86/APKINDEX.tar.gz                                     ERROR:  temporary error (try again later)                     WARNING: Ignoring APKINDEX.adfa7ceb.tar.gz: No such fi le or directory                                        fetch ity/x86/APKINDEX.tar.gz                                ERROR: nity: temporary error (try again later)                WARNING: Ignoring APKINDEX.efaa1f73.tar.gz: No such fi le or directory                                        ERROR: unsatisfiable constraints:                        openssh (missing):                                       required by: world[openssh]  

    opened by DHCMediWay 18
  • Escape Key

    Escape Key

    Hi, I have a feature suggestion, I'm using this application with iPad Air 4 and Apple Magic Keyboard and in this keyboard the left upper key is: §, Can you please add a option in the external keyboard menu for using this key as a escape key. Thanks, Yakov S.

    opened by Jaykov-s 0
  • 8059: Function not implemented

    8059: Function not implemented

    8059: Function not implemented

    phoneid--ljcucc:~# apk add nnn
    (1/2) Installing fts (1.2.7-r1)
    (2/2) Installing nnn (4.1.1-r1)
    Executing busybox-1.33.1-r6.trigger
    OK: 270 MiB in 137 packages
    phoneid--ljcucc:~# nnn
    8059: Function not implemented
    opened by ljcucc 0
  • Home assistant installation

    Home assistant installation

    Home assistant installation

    I am trying to use an Iphone instead of a Raspberry Pi to handle Home Assitant. The reason is... I already have an old iphone I could dedicate to this purpose, and I am probalbly not the only one.

    Also, I would rather avoid jailbreaks to make it easier for anyone.

    What works

    From my laptop, I can easily connect to my iphone using ssh. I am thinking "perfect, let's do it"


    ish is using an Alpine distribution. Home assistant uses debian. So it requires a bit of work to install manually packages, which I did, but still I can't make the installation work. Anyone already tried ? Any clues why I may not be possible ?

    opened by guillim 3
  • Pycryptodome: Illegal Instruction

    Pycryptodome: Illegal Instruction

    illegal instruction at 0xf6edc2cd: 66 0f 71 d2 08 66 0f db

    Installing pycryptodome: $ python3 -c 'from setuptools import setup; setup()' easy_install pycryptodome

    Script that crashes:

    from Crypto.PublicKey import RSA
    from Crypto.Signature import PKCS1_PSS
    from Crypto.Hash import SHA256
    key = RSA.RsaKey(n=125077528314931297006326963038847725769874511389453959646191151532116084270760414607995902789984898784809091694426860715965637274176324249985555765292210343004248501382602620649197884798533146377507599613648845911285708138313681371648868072467013640857168852486854538851398508562978142162223489750293964582113, e=65537, d=9344028237940455470085246670402955053928400869169577283484930312666743192237102551547186170556572080663217921722292904242912554654123373482601904677825682124136894957740943526645474560879165773604234409899040757383871185854343899725113739742734009589435323223684185601702359096689104406133096460040762269313, p=10197148797446210932926963565344298268807369617140724808135944110409261431140003366476367070791356552919833380439617028027996366732854251321237691775560443, q=12265931467652595074996383734017891354836334732774894333094649856326410065559201715002652320548343993633202781600913543783646735217423833127928106389012691, u=4545975502251523288161807752504658769418750180867466006414854572603632456429539608902609444150424369731531922872458978993366551408959534856117149641033167)
    h ='')
    signed_data =

    unconfirmed emulator 
    opened by xloem 4
Linux emulator for iOS
Linux shell for iOS

iSH A project to get a Linux shell running on iOS, using usermode x86 emulation and syscall translation. For the current status of the project, check

iSH 12.1k Jun 24, 2022
A shell for unix and linux systems

Snash A shell for unix/linux A shell for unix and linux systems. This is still a work in progress and ALOT has yet to be implemented. Snash stands for

Reinhold 4 Dec 21, 2021
Filament is a real-time physically based rendering engine for Android, iOS, Windows, Linux, macOS, and WebGL2

Filament Filament is a real-time physically based rendering engine for Android, iOS, Linux, macOS, Windows, and WebGL. It is designed to be as small a

Google 14.2k Jun 20, 2022
Oxygine is C++ engine and framework for 2D games on iOS, Android, Windows, Linux and Mac

BUILD AND RUN See oxygine-framework/readme/ folder. It has instructions on how to build and run oxygine on different platforms. Wiki available at http

Oxygine 728 Jun 17, 2022
Sega Master System / Game Gear / SG-1000 emulator for iOS, macOS, Raspberry Pi, Windows, Linux, BSD and RetroArch.

Gearsystem is a very accurate, cross-platform Sega Master System / Game Gear / SG-1000 emulator written in C++ that runs on Windows, macOS, Linux, BSD, iOS, Raspberry Pi and RetroArch.

Ignacio Sanchez Gines 161 Jun 22, 2022
Hobbyist Operating System targeting x86_64 systems. Includes userspace, Virtual File System, An InitFS (tarfs), Lua port, easy porting, a decent LibC and LibM, and a shell that supports: piping, file redirection, and more.

SynnixOS Epic Hobby OS targeting x86_64 CPUs, it includes some hacked together functionality for most essential OSs although, with interactivity via Q

RaidTheWeb 40 May 27, 2022
A custom macOS statusbar with shell plugin, interaction and graph support

SketchyBar This is a rewrite of the spacebar project, which itself is a rewrite of the statusbar code from yabai. Features: As many widgets as you lik

Felix Kratz 734 Jun 24, 2022
The simple UEFI application to create a Windows Platform Binary Table (WPBT) from the UEFI shell.

WPBT Builder This is a simple UEFI application to create a Windows Platform Binary Table (WPBT) from the UEFI shell. Motivation WPBT is one of the Adv

Satoshi Tanda 60 Jun 20, 2022
Make BAD USB to Reverse Shell with Arduino Digispark (recommended with attiny85)

Make BAD USB to Reverse Shell with Arduino Digispark (recommended with attiny85) Cara Pakai Pastikan Anda telah menginstal Driver Digispark dan mengon

Edo 3 Apr 17, 2022
Shell program written in C to implement various system calls, with support of executing commands, output redirection and signals.

Use ./shell command to start the shell. $<space>path/executable to run the executable(please specify the path without beginning it with "/"). Eg. type

Ayuj Panchal 1 Nov 15, 2021
Creates a virtual disk in memory and provides the user a shell to interact with it

Tiny-File-System Creates a virtual disk in memory and provides the user a shell to interact with it Known bugs with Export missing chars at the end of

Alex Fuller 2 Nov 23, 2021
Wayfire plugin for handling touchpad gestures globally in a layer-shell surface

wf-globalgestures Global touchpad gestures plugin for Wayfire: implements a special protocol (also in this repo) that lets clients request that a part

null 4 Jan 18, 2022
FogCube shell written in C++

IDK This is just a program that lexing and parsering an input from the prompt. What this program actually? Well, I dont know, I make this program just

null 1 Dec 28, 2021
This project simulates the functionality of the Unix Bash shell.

Minishell This project simulates the functionality of the unix Bash shell. Description The project aim was to recreate the functionality of the unix B

Andreas Gebert 0 Jan 6, 2022
Simple mini-shell coded in C Language

Mini Shell Simple mini-shell coded in C Language, i had a lot of informations and experiences on Linux processes and some low level stuff while coding

Sc1r3Cr0w 4 Jun 16, 2022
Ccd - Edge first cd replacement tool for Windows cmd shell.

Cursorial CD Cursorial CD, or ccd for short, is a cd replacement for Window's cmd shell. Unlike cd, it operates on an edge first search, so you can qu

Scott Seligman 5 Feb 2, 2022
Minishell - This project aims to recreate most of the bash shell.

minishell Contents Info How to use Clone repo and submodules Linux dependencies MAC dependencies Compile and execute Install Features Built-in command

izenynn 2 Jun 9, 2022
Microshell - a lightweight pure C implementation of shell emulator dedicated for embedded bare-metal systems.

MicroShell Lightweight pure C implementation of virtual shell, compatible with VT100 terminal. Support root tree, run-time mounting paths, global comm

Marcin Borowicz 88 Jun 18, 2022
An extension manager for browsing and installing GNOME Shell Extensions.

Extension Manager A native tool for browsing, installing, and managing GNOME Shell Extensions. Written with GTK 4 and libadwaita. Features The tool su

Matt Jakeman 363 Jun 27, 2022