KBOX frequently-asked questions

What is KBOX for?

KBOX is a set of libraries, scripts, and utilties that allows experienced Linux users to manage their Android devices from the command line, in a way that is more like a desktop Linux system. Its main goal is to obviate the hassle of rooting or modifying an Android device, just to be able to run simple command-line tools. Android is based on the Linux kernel, but only provides an impoverished set of utilities -- far from what a desktop Linux user would be used to. Terminal emulators are available for Android, and these provide a console environment; but on its own a terminal emulator is of limited use. KBOX3 provides utilties like ssh, vim, and Perl, to be used in conjuction with a terminal emulator. Because KBOX provides applications with a virtual filesystem that looks more like real Linux than the Android filesystem does, it is much easier to port Linux applications to KBOX3 than to native Android.

What Linux utilities does KBOX provide?

As well as core Linux command-line utilies the following, more substantial, packages have been ported to KBOX3.

Development tools: gcc, Perl, Python, Java

Math: bc, KCalc

Networking: Curl, Dropbear, ftp, Lynx, rsync, utelnetd

Text processing: groff, gawk

Interactive fiction: frotz, glulxe, frobtads

Source management: git

Privacy/encryption: GnuPG, KCrypt

Editors: Vim, Nano

Compression: zip, unzip, unrar

For a full list, see the Downloads page. Please note that not all utilities are avaibale for all device architectures.

How is KBOX4 different from KBOX3?

To the end user, there is little difference. The differences are in the way that the code is build. I hope that the new build scheme will make it easier to support multiple device architectures. Most utilties have been updated since the KBOX3 release, but the updates are unlikely to be revolutionary.

What about even earlier versions?

I'm assuming that there are no installations of KBOX(1) and KBOX2 still in use. These were pretty crude in comparison to the later versions. I used to maintain a version of KBOX that was integrated into a terminal emulator, but it was something of a chore.

What does KBOX stand for? Is it connected with anything else called KBOX?

KBOX originally stood for "Kevin's implementation of Busybox", because it grew out of my attempt to install Busybox on non-rooted Android device. These days, Busybox is just the start, but I have retained the name, since I have no imagination. KBOX is unconnected with anything else with the same name. There is at least one radio station called KBOX and, perhaps somewhat confusingly, the name is also used by a project to port Linux to Microsoft XBox.

How many people use KBOX?

I don't have any way of knowing that. In 2013, the KBOX base system was downloaded from my web server about 12,000 times. How many of those downloads developed into regular use, I don't know. About a hundred people have so far contacted me to ask questions, so I guess the number of regular users is between a hundred and 12,000.

Does this root (or otherwise modify) my device?

Not at all. The whole purpose of KBOX is to provide a Linux-like command prompt environment on a completely stock Android device. It won't help you to root your device, even if you want to.

Does running KBOX remove the need to root my device?

That depends on why you might want to root it. KBOX removes the need to root your device simply to run an ssh client session, or edit a file using vim; but it doesn't provide any system-level access. It won't allow you to install new kernel modules, or change the contents of the Android root filesystem.

Will KBOX run on a rooted Android device?

Probably, but what would be the point? If you're rooted, you can install whatever you like, wherever you like.

What devices/versions does KBOX run on?

KBOX is designed to work with ARM CPU-based devices, running Android version 5.0 ('Lollipop') and later. It might work with earlier Android versions, but there has been little testing. The following, at least, have been reported to work:
  • Google Nexus 7 (2012), with Android 5.0.2
  • Google Nexus 7 (2013), with Android 4.4.4
  • Samsung Galaxy Tab 3, with Android 4.4.2
  • Samsung Galaxy S3, with Android 4.4.2
  • Samsung Galaxy Note 10.1 (2014), with Android 5.5.1
  • ODroid XU, with Android 5.1
  • Samsung Galaxy Alpha, with Android 4.4.4
  • HTC One M8S, with Android 5.0.1 (M8 and M9 should also be OK)
  • Sony Experia Z3 Compact, with Android 5.0.1
  • Sony Experia Z1, with Android 4.4.4
  • Asus C100P Chromebook, with Android 6.0
  • Acer R13 Chromebook, with Android 6.0 (x86 build)
Bear in mind that most Linux utilities were designed (or were derived from utilities that were designed) to output to a screen with a width of at least 80 characters. Very small devices might not be very useable, even if KBOX runs on them, unless you have very good eyesight.

What about 64-bit Android devices?

Good question. Everything in KBOX3 is built for a 32-bit ARM or x86 . However, the small number of 64-bit devices I have tried (essentially the latest HTC offerings) do seem to provide good 32-bit compatibility support, and KBOX does seem to work on those devices.

However, you won't be able to invoke any 64-bit utilities from the KBOX prompt. The reason for this is that KBOX needs to load the libfakechroot.so library into the process being executed, and (at least on the devices I have tried) you can't load a 32-bit library into a 64-bit process.

That won't be a problem when running anything provided by KBOX3, but it will be a problem if you try to invoke system utilities; even /system/bin/sh will fail (just by way of illustration; there should be no practical need to invoke the stock Android shell). I suspect (but have not verified) that running Java utilities in KBOX will be problematic on a 64-bit system, because we need to run the (64-bit) Android JVM to do this. There could conceivably other problems as well.

I guess that one day I will have to bite the bullet and build a 64-bit version of KBOX, but that's a collossal task, and one that I won't undertake until it becomes absolutely essential.

What does the KBOX base system provide?

The base system provides Busybox (built to offer about 50 utilities), and some other fundamental utilities that most of the other packages depend on.

Why is it so hard to do what KBOX does?

People often e-mail me with questions like "Why does XXX not work properly?" or "Whey do I get error message YYY with Android 5.1 when I didn't get it with 5.0?" Occasionally -- and it is very, very occasional -- somebody will e-mail me a rude message full of curse-words in capital letters because something didn't work as expected. That's fair enough, of course -- people are entitled to expect a better service from somebody who is working free-of-charge in his spare time. The problem is that I don't have any control over Google. Android is not designed for running console utilities, and Google (I presume) doesn't give a damn whether they work or not. Every new release of Android breaks something in KBOX that I have to fix. I don't suppose Google does this on purpose, although sometimes the changes are so mutton-headed that it certainly seems that way. Moreover, there is not the uniformity of hardware in the Android world that there is with, say, Apple or Blackberry mobile products, and Android device vendors modify and extend the base Android system in all sorts of ways. Consequently, keeping KBOX working at all is an uphill struggle. That it should work flawlessly on all possible Android devices is an impossible dream.

How do I install KBOX?

Essentially, copy the base system installer to your device, and run it. Then download whatever packages you need and use the dpkg utility to run them. For full instructions see the installation page.

How do I uninstall KBOX3?

KBOX becomes part of the terminal emulator you install it with. Uninstalling the terminal emulator will remove KBOX and all files created with it. The exception is files created on the SD card (or external storage). These will survive uninstallation. Alternatively, just delete the kbox4 directory using ordinary Linux commands in the terminal emulator.

Can I install KBOX from the Android Market / Google Play?

I will never be providing KBOX via Google Play, for two reasons. First, Google charges developers to upload apps, and since I make no money from KBOX, I'm unwilling to make this expenditure. Second, KBOX isn't an app. It's a bunch of files that are designed to be installed into an existing terminal emulator app. I used to distribute a version of Jack Palevich's terminal emulator that KBOX (version 1) built in, but this proved too time-consuming to maintain.

A number of products are available, from Google Play and elsewhere, that do integrate some version of KBOX or another. Some of these are commercial, or carry advertisements. The developers of these products have my full support, but I don't endorse any of them, because I haven't tried them.

Is KBOX connected with Debian?

This question sometimes crops up because KBOX packages are distributed in .deb format. KBOX has no connection with any other Linux distribution; it uses Debian package format because Busybox has built-in support for that format, so I don't have to write another package manager.

Can I install .deb packages from other repositories?

This will almost certainly not work, even if KBOX can process the package files. KBOX is designed to run code specifically compiled and linked with Google's native-code development tools for Android.

How does KBOX provide a root filesystem on an unrooted device?

See the how it works page.

What is my user ID?

Or "Why is my user ID so stupid?" Run id to find your user ID. Android is not a multi-user system (until 4.2 -- see below); user IDs are used to isolate apps, not users, from one another. Each app gets a user ID, which is typically a sequence number. In Android 4.2 and later, each app has a user ID comprised of the 'real' user ID (the login ID) plus a sequence number; but it's still one-user-ID-per-app. There's no straightforward way to make the user ID look sensible within the KBOX shell, without breaking something somewhere else (at least, not that I have been able to find). When an application queries the system for your user ID, will either get "kbox" or the meaningless jumble described above, depending on how it makes the queury.

Where is the SD card directory?

It's at /sdcard. The external SD card, if one is installed, is probably at /storage/extSdCard (Samsung devices) or /storage/ext_sd (HTC and Sony devices). In practice, /sdcard is probably a link to /storage/sdcard0. The /sdcard and /storage directories are actually ordinary parts of the Android filesystem, that are imported into the KBOX virtual filesystem. The same applies to /dev and /proc.

Please note that, at the time of writing, the Android emulation on Chromebooks provides no access to the external SD card at all.

How do I change the user's home directory?

Edit /etc/profile and add a statement HOME=/something. In principle this afffects all users, but KBOX, like Android, is a single-user system, so it makes no difference.

How do I customize the shell (setting a different PATH, etc)?

Edit /etc/profile. Please refer to the comments in this file -- they indicate lines that should not be changed.

How do I run 'su' or 'login'?

You can't, really. These utilities will not even compile on the Android platform, and there is no system-level infrastructure to support them even if they did. The executable /bin/login is a functionless stub, designed to support applications that insist on being able to run it.

Can I log into KBOX remotely?

Maybe. Packages are available to provide telnet and ssh daemons, but whether the Android platform will allow remote clients to get access is very much device-dependent. Some users have reported that they can get access to ssh on KBOX only if they first make an outgoing ssh connection from kbox to something else. This seems to fool the Android firewall into thinking that the inbound connection is part of some established TCP session. This is of limited usefulness, of course. Sadly, without root access it is not possible to reconfigure the firewall. No recent Android device I have tried has allowed incoming connections on any port.

How do I see the original Android root directory?

The KBOX root directory (/) is the root of the KBOX virtual root filesystem. To see the original Android root, cd to directory /android_root. Be aware that there's very little to see there if you're an unprivileged user.

Why do advanced features like syntax highlighting not work in vim?

They do -- but you actually need to be running Vim not vi. Busybox contains a (limited) implementation of vi; if you just run vi at the prompt, that's what you'll get. Install the Vim package, and run vim instead.

How do I type the 'Escape' key in Vim?

Or the pipe (|) symbol? Or the Tab key? Many Linux utilities are intended to work with a fully-featured keyboard, with a complete range of punctuation and symbols. Most Android virtual keyboards fall far short of this ideal. Some terminal emulator apps provide mechanisms to map virtual keyboard operations to commonly-missing symbols. For example, I map the 'volume up' button on my device to the 'Escape' key, because you can't really use Vim without an Escape key (or at least a Ctrl key -- Ctrl+[ should generate Escape.) It has to be noted that even the use of an external keyboard does not necessarily fix this problem -- my BlueTooth keyboard doesn't have an Escape key either. However, it has most other keys that I need, and I can still get the Escape keystroke by pressing Ctrl+[.

Where an external keyboard is not available, I recommend the use of a 3rd-party virtual keyboard that is designed for serious use. I normally use Klaus Weidner's Hacker's Keyboard (available from the Android Market) with KBOX.

Why does ping not work?

ping requires root permissions. On a desktop Linux system, ping is typically configured with SUID flag set -- that is, it runs as root whatever the user. Android is not configured this way (thanks, Google).

How do I add a static hostname (e.g., to /etc/hosts)?

You can't. The Android platform provides no mechanism for adding static hostname references. The hosts file is just a stub, and even if entries are added to it (which would need root permissions) they still wouldn't be read. To use static hostnames you'd need to provide your own name resolution library, and link all utilities against that instead of the Android C library. It's possible in principle, but a lot of work for little gain.

What is involved in porting Linux utilities to KBOX?

In simple cases, it's just a matter of cross-compiling the code using the C/C++ compiler provided in the Android Native Development Kit. In practice this often means building a bunch of libraries that the utility needs, in addition to the utility itself. Many utilities have dependencies on ncurses, for example, which is fiddly to build for Android.

It's important to understand that KBOX will only properly run code compiled with the Android NDK, and dynamically linked against the Android 'Bionic' C library. Code that is linked against, for example, glibc, or statically linked, will probably run; but it won't be able to take advantage of the KBOX virtual root filesystem, so the code will have to be modified (perhaps extensively) to point to the real filesystem locations, using the $KBOX environment variable to provide a pointer to the KBOX installation.

Bionic is a pretty rudimentary C library, and many functions that are found in glibc are not provided. In general, these are functions that make no sense in the Android environment (functions for managing user credentials, for example). Utilities that use these calls have to be modified.

KBOX is designed for running console-mode applications. At present, there's no realistic prospect of port X applications to KBOX. It's possible in theory, but the amount of work involved is prohibitive.

For more information on building C utilties for Android using the Google tools, see here.

What about porting utilities that play audio?

This is a tricky one. At present, Android does not expose the underlying Linux sound drivers to applications. In fact, as of Android 5, unprivileged applications can't even list the contents of the /dev directory to see what the implementation is. I presume it's still ALSA, but who knows? At present the only way to produce sound is to use the OpenSLES API provided by Android. KBOX includes a simple utility android-audio-sink that reads raw audio or WAV data and plays it using OpenSLES. The intention here is that an application that needs to produce sound will feed it into kbaudiosink, perhaps via a named pipe. So far the only audio application I've tried this with is the espeak text-to-speech system. It does work, but it's not a very elegant approach. Nevertheless, until Google does the Right Thing and makes the actual audio subsystem available, I doubt we can do much better.

Will you port application XXX?

By all means ask. Mostly the utilities I've ported to KBOX3 are the ones I use myself; but I'm happy to consider others. However, if it's not something I'm likely to use myself, I probably won't be able to do it if it isn't straightforward.

Please be aware that I, and other contributors, do have a bunch of stuff we built for KBOX but never formally packaged or distributed, because there doesn't seem to be any demand. For example, I know that Lua builds cleanly on KBOX, but I've never made a package for it because nobody has asked.

When is X support coming?

Short answer: probably never.

Longer answer: I am in two minds whether this is even an avenue worth exploring. On the one hand, there are certain X applications that could be useful on Android devices, and for which there is no native Android alternative. On the other hand, it would involve a great deal of work and, in my view, there aren't all that many X applications that make much sense to run on a handheld device, and which don't have a native equivalent. I'm often told that this job should be simple now that there are X servers for Android; but the existence of an X server is only the start of the problem. Most X applications have dependencies not only on X and its libraries, but also on various toolkits like GTK+ and Qt. They very often have dependencies on Linux subsystems that wouldn't make any sense on Android -- DBus, for example. Porting all this lot to KBOX would be a colossal undertaking. I certainly have no enthusiasm for spending weeks of evenings just to see xclock and twm running under KBOX. Life's too short.

What might sway me on this matter is to be shown a killer app that requires X support, doesn't have an Android equivalent, and has no onerous dependencies on desktop Linux infrastructure.

Can I build applications for KBOX within KBOX itself?

Most of the KBOX utilities have been cross-compiled using the Android NDK on a Linux PC. However, a C compiler is available for KBOX, as are certain common build tools (make, etc). So it's certainly possible to build some applications on the Android device itself. Building this way solves a bunch of problems that are routinely associated with cross-compilation; but if the build is complicated enough that it needs to be performed this way, you might well find that it fails for other reasons -- because, for example, KBOX is missing certain utilities that the build needs.

Incidentally, I do have "development" packages for common libraries like ncurses, that include the C header files that you need to build applications that use those libraries. I don't routinely distribute them because I'm not aware of anybody except me who uses them, but do ask if you need something like that.

What about scripting languages?

Reasonably complete implementations of Perl and Python 3 are available. If you have a pressing need for some other language (Lua? Ruby?) please ask -- I can at least give an idea whether it's likely to be practicable.

How to I install an updated version of an optional package?

Just run dpkg -i [package].deb, as for installing. The new version will overwrite the old one.

How do I install a later version of the base distribution?

This is tricky. You can't do it from within the KBOX shell, because many of the files that will need to be overwritten will be in use. The only way to update the base system that I can think of is as follows.

1. Set the terminal emulator to use the default shell, /system/bin/sh -, rather than the KBOX shell.
2. Close the terminal emulator completely.
3. Restart the terminal emulator.
4. Install the base installation, exactly as if this were a fresh install (see installation page).
5. Set the terminal emulator to use the KBOX shell again.

Why does the man command no longer work?

man is provided by Busybox, but all it does is feed manpages into the text formatting utility nroff, which is not provided. I removed nroff from the base system because it is rather large, and I wanted to keep the base system minimal in KBOX3. So to read manpages, you will need to install the groff package. Please be aware that if your terminal emulator is set for fewer than 80 columns, manpages will likely be formatted badly.

Why do some packages install in /bin, some in /usr/bin, etc?

No good reason. KBOX is based on contributions from many different people, all of whom like to do things in their own way.

Can I have the source code for KBOX?

The build scripts are on github, along with the small amount of original code. The code for the actual utilities is all open source, and not distributed as part of KBOX. The KBOX distribution on githib contains the patches that modify the open-source "upstream" code to work with KBOX, and no more code than that.

Can I contribute to KBOX?

Yes, please! About a half-dozen people have contributed packages to the project that they either built using Google's Android NDK or built on an Android device after installing gcc, make, etc. Many more people have tried KBOX and reported bugs or made suggestions for improvements, and these are also valued contributions.