• The KBOX3 project
KBOX3 frequently-asked questions
What is KBOX3 for?
KBOX3 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
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 KBOX3 provide?
As well as core Linux command-line utilies the following, more
substantial, packages have been ported to KBOX3.
gcc, Perl, Python, Java
Networking: Curl, Dropbear, ftp, Lynx, rsync, utelnetd
Text processing: groff, gawk
Interactive fiction: frotz, glulxe
Source management: git
Privacy/encryption: GnuPG, KCrypt
Editors: Vim, Nano
Compression: zip, unzip, unrar
For a full list, see the Downloads
How is KBOX3 different from KBOX2?
See this page.
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 KBOX3 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 KBOX3 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 KBOX3 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:
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.
- 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
What about 64-bit Android devices?
Good question. Everything in KBOX3 is built for a 32-bit ARM platform. 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 KBOX3 does seem to work on those devices.
However, you won't be able to invoke any 64-bit utilities from the KBOX3 prompt.
The reason for this is that KBOX3 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;
/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 KBOX3 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 KBOX3, but that's a collossal task, and one
that I won't undertake until it becomes absolutely essential.
What does the KBOX3 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
Why is it so hard to do what KBOX3 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 4.2.3 when I didn't
get it with 4.2.2?" Occasionally — and it is very, very occasional — somebody will e-mail me a rude message full of curse-words in capital
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 KBOX3 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 KBOX3
working at all is an uphill struggle. That it should work
flawlessly on all possible Android devices is an impossible
How do I install KBOX3?
Essentially, copy the base system installer to your device, and run it.
Then download whatever packages you need and use the
utility to run them. For full instructions see the installation page.
How do I uninstall KBOX3?
KBOX3 becomes part of the terminal emulator you install it with. Uninstalling
the terminal emulator will remove KBOX3 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
directory using ordinary Linux commands in the terminal emulator.
Can I install KBOX3 from the Android Market / Google Play?
I will never be providing KBOX3 via Google Play, for two reasons.
First, Google charges developers to upload apps, and
since I make no money from KBOX3,
I'm unwilling to make this expenditure. Second, KBOX3 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 had 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 KBOX3 connected with Debian?
This question sometimes crops up because KBOX3 packages are distributed
.deb format. KBOX3 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
Can I install .deb packages from other repositories?
This will almost certainly not work, even if KBOX3 can process the
package files. KBOX3 is designed to run code specifically compiled and linked
with Google's native-code development tools for Android.
How does KBOX3 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).
Where is the SD card directory?
/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 directories are actually
ordinary parts of the Android filesystem, that are imported into the
KBOX virtual filesystem. The same applies to
How do change the user's HOME directory
/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)?
/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. These utilities will not even compile on the Android platform,
and there is no system-level infrastructure to support them even if
Can I log into KBOX3 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.
How do I see the original Android root directory?
The KBOX3 root directory (/) is the root of the KBOX virtual root
filesystem. To see the original Android root,
/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
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
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 KBOX3?
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
glibc are not provided. In general, these are
functions that make no sense in the Android environment (functions for
manage user credentials, for example). Utilities that use these calls
have to be modified.
KBOX3 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
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. KBOX3 includes a simple utility
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 KBOX3 but never formally packaged or distributed, because there
doesn't seem to be any demand. For example, I know that Lua builds cleanly
on KBOX3, but I've never made a package for it because nobody has asked.
When is X support coming?
I am in two minds whether this is 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 KBOX3.
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 KBOX3 within KBOX3 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 (
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,
KBOX3 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?
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.
I have 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
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
No good reason. KBOX3 is based on contributions from many different people, all
of whom like to do things in their own way.
/bin, some in
Can I have the source code for KBOX2?
Please see this page.
Can I contribute to KBOX3?
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
etc. Many more people have tried KBOX3 and reported bugs or made suggestions
for improvements, and these are also valued contributions.