• The KBOX project
Please note that this page is obsolete. An all-new version of KBOX is now
available — see the KBOX2 project pages
KBOX — a miniature Linux distribution integrated with a
terminal for non-rooted Android devices
[Now with camels! A package is available
that provides a Perl interpreter for the KBOX environment. See
the Optional packages section for details.]
KBOX is a project to create a miniature Linux distribution
for non-rooted (i.e., unmodified) Android devices, integrated directly
into Jack Palevich's Android terminal emulator (see here). Installing the Android
package (see below) gives you the terminal emulator, a decent set of
Linux utilities (supplied by busybox),
clients and servers, and a few other things. In addition, there are a
number of add-on packages for expanded functionality.
I do want to stress that the credit for developing the terminal emulator
and making it open source belongs to
Mr Palevich — I have not changed it beyond the minimum needed to
integrate my utilities. You can use my package side-by-side with the
original terminal emulator on the same device: they should not clash.
Uninstalling the package will remove the whole thing including add-on
packages, except for data created by the user on the SD card.
The technical background to the
KBOX project is explained
here and here. Android is not Linux, and there's a limit to how far one can emulate
a desktop Linux on a non-rooted Android devices. I would certainly recommend
reading the more technical documents to get an idea of why
operates the way it does.
Please note that 'download' links are hidden in the document, to encourage
people to read at least some of this stuff before leaping into installing
[Update, March 2013: I've had a few reports of KBOX not working on
Android 4.2 devices, although it seems to be fine on 4.1. Because it fails
with no diagnostic output, and I don't have a 4.2 device to test on, I am
unable to investigate this problem. In addition, a number of people have
expressed an interest in running KBOX with a different terminal
emulator. Because many people don't want to read all the technical background
and set everything up from scratch (although that would be the best
way) I have documented a manual procedure that will work with other
terminal emulators, and should work with Android versions after 4.2
as well. The details are
Limitations — please read this
KBOX works on at least some Android 4.x, 3.x and 2.3 devices.
It will not work on releases earlier than 2.3. DNS name resolution
does not seem to work under 2.x, although it does under 3.x. I don't know why,
and have no clear way to find out. DNS resolution is fine (for me)
under 4.0. I have had reports of KBOX not working on 4.0 platforms, but
it isn't clear why, or whether it would have worked on the same hardware
with Android 3.x.
2. KBOX won't ever be appearing on the Android market. To install it you'll
need to download the packages and optional components and install from
the Android browser or a file manager. This is disallowed by default — you'll
need to enable the setting 'Allow installation of non-market applications'
in the Android settings applet.
3. There is no X server for Android (yet). It's likely that many X applications
can be built to run on Android but, without an X server, it's not clear
that there's much point. A port of Xvnc is available, so it's possible
in principle to run X applications using that and a VNC viewer. While
academically interesting, this doesn't seem very practical to me. My point
is that there's little point asking me if I can port Firefox or OpenOffice — it's terminal utilities only at the moment. [Update, January 2013:
it's been brought to
my attention that there is some work in progress to produce a native X
server for Android. I'm not sure how stable this project is yet.]
4. Fiddling with Linux is a hobby, not an occupation. If it doesn't work for
you, I'll very likely not have time to fix it. Full source code is available,
if you want to fix it yourself :)
KBOX is a miniature, single-user Linux distribution, integrated into a
terminal emulator for Android. It's single-user because there is no notion
of user credentials, and all files belong to the same user. The actual
user ID is assigned by the Android package installer, and is arbitrary.
Because an unpriveleged user has very limited access to the filesystem, the
entire root filesystem is located somewhere under the Android app's preferences
directory. From a Linux perspective this makes no sense, but is necessary.
Most Linux utilities — even simple ones — expect a conventional file
layout, with directories '/etc', '/usr', etc. This is impossible in this
application, and most of the Linux utilities that have been ported to
KBOX have required some reworking to account for the
unconventional file layout. For the most part, however, the file layout
is not particularly visible to the user.
By default, the user's home directory is
, where 'user_id' is the arbitrary ID created by Android. The
KBOX user has full read-write access to the SD card area.
It's important not to expect any file to be in the place it would be on a
conventional Linux system — all the conventional locations are write-protected
on a non-rooted device. The environment variable
points to the root of the
KBOX installation, below which you'll
find the usual Linux directories.
Last update: October 25, 2012
The basic distribution contains Jack Palevich's terminal emulator,
the the ssh server and client from the
I've tried to include as many of the busybox utilities as I could get to
build under the Android NDK. Some only work in part (e.g., you can get
the date, but not set it) because of Android limitations and security
restrictions. But the basic stuff — find, grep, tar, vi — is all there.
Provided by dropbear. Keys will be cached in $HOME/.ssh in
the usual way. No non-standard arguments need be used, but bear in mind
that you'll have to specify a specific user for the remote service because
the Android user ID is arbitrary in a non-rooted device.
In this system,
scp is actually a shell script that runs the
proper scp with arguments appropriate to the unconventional file layout
This is a somewhat modified version of the dropbear ssh server.
On an incoming connection it launches
kbox_shell instead of
the Android shell, so that the user is provided with a workable environment.
kbox provides a script
ssh_daemon.sh that will launch the
ssh server with the appropriate arguments, specifying user credentials
and port number on the command line. The port number comes from
$KBOX/etc/kbox_ports.sh. As always, the port number must
be above 1024 for non-root usage. In addition, the user ID (specified
by the -U argument) must be the user ID of the terminal emulator
app running the script.
ssh_daemon.sh takes care of these
issues, and can be used as a template for more appropriate customization.
Note that this script sets the current username as the password, which
isn't hugely secure.
The script will read an RSA server key from $HOME/.rsa_host_key. The
dropbearkey utility can be used to create this key, but
it should be created automatically when a user logs in on
console for the first time.
In order to connect to the sshd server run as described above, clients
need to specify the port number on the command line (e.g.,
ssh -p 10022 [my_andoid_ip]).
At present there are only a few optional packages.
If there is interest, I might be able to
provide other Linux utilities as add-on packages.
How to install optional packages
Packages are installed using the
dpkg utility (supplied as part of
busybox). Please note that you can install (
dpkg -i) and
dpkg -l) packages but not remove or update them. This is
a known limitation of busybox, and one that doesn't have a fix at present.
The simplest way to install is probably to download using the Android browser,
which will put the files in
/sdcard/Downloads. Then in the
$ dpkg -i /sdcard/Download/[file].deb
It should not need to be said, but just in case: although there add-ons are
in Debian package format, an attempt to install any other Debian package
will most likely fail catastrophically.
A simple utility I wrote to play music files at the command line.
$ andplay [files...]
andplay has the slight advantage over utilities like
mpg123 that all it does is
invoke the built-in media server in Android. Memory and CPU usage are
therefore very low.
The scientific calculator application. I have included the general
function library from
bc script will load this automatically. The
built in functions don't work anyway, for some reason. So if you want sine
sin() rather than the older
etc. But look at
phodd.net for full details.
A simply utility for extracting and formatting text from EPUB e-books.
epup2txt my_book.epub|more makes a servicable reader for
EPUB e-books althrough there are, of course, fully featured graphical
EPUB readers for Android.
For more information, see here.
frobtads is an interpreter for TADS games like 'Ecdysis.'
If you don't know what that means, you probably won't be
interested in this. For more information,
frotz is an interpreter for z-code games like 'Zork' and
'Sherlock'. If you don't know what that means, you probably won't be
interested in this. This version supports text styles and colouring, but
not sound (it requires old-style OSS audio drivers, which Android does not
provide). If you install an Android keyboard with cursor keys, it supports
line editing and history, too. Unfortunately, as with any terminal-based
application, fonts are fixed pitch, and this can be irritating when reading
large amounts of text. From this point of view, 'ZMPP' is a better
z-code interpreter, but Frotz under KBOX is faster, because it is written
entirely in C and runs natively on the Android OS, and supports line
editing, ASCII art, menus, and many other features that the Android
apps lack. For more information, see here.
The GNU version of the
awk text processing language.
I'm not really an
awk user myself, so there's not a lot I
can do to check this works fully. Please note that I haven't included
the source-code library files (*.awk) in this package. Presumably they
could be copied from desktop Linux installation if required.
glulxe is a console-based runtime environment for for
Glulx interactive fiction system. It supports line
editing and simple text formatting.
For more information about interactive fiction under KBOX,
KCalc is a lightweight, command-line calculator, intended to fill the
bc and Matlab. For more information, see
KCrypt is a simple, command-line file encrypter and obfuscator. It is
designed to offer reasonable security, while still being convenient to
use. For full details, see the main project page
Please bear in mind that KCrypt was originally a Windows program; it
has had relatively little testing on Android. Please use with
Because cross-compiling Perl is a real pain, I have extracted a
pre-compiled version from the Android Scripting Environment project,
and re-packaged it as an add-on package for KBOX. The original
executable is renamed
becomes a wrapper script for that binary, with the appropriate
environment for use with KBOX.
This version of Perl is 5.10.0, and it is a fairly minimal build — a lot of the optional components are not included, particularly those
that require supporting C libraries that might not even exist on Android.
There is no support for big numbers (
use bigint, etc)
However, it seems basically functional for routine file and text
rsync as a client
rsync can be used as a client with the default use of
ssh to start the server on the remote system. It can also be used to
talk to a stand-alone rsync daemon. I haven't (yet) included an rsh client,
so the use of rsh to start a remote session (
rsync as a server
At present, rsync can only be run as a server in stand-alone daemon mode.
This mode does not
require any other dameon processes (e.g., sshd) to be running on the device.
The potential downside is that there is no authentication of clients, so
such a daemon should probably not be left running for extended periods.
The command line to start the rsync daemon is:
% rsync --daemon --config [config_file] --port [port] --no-detach \
You don't need to redirect the log to
/dev/null — but the
standard log location won't work, so you'll have to send it somewhere.
The config file specifies what files will be made available in what
modes, and how they will be identified by the client. A sample config
file is provided in $KBOX/etc/rsyncd.conf. This config makes all files
available, read/write, under the identifier 'all'. The client will
do transfers like this:
% rsync --port [rsync_port] [device_ip]::all/path/to/file [local_path]
This is essentially the normal usage of rsync as a client, except that
the path is prefixed ':all', and the port number is given explicitly.
Note that the rsync daemon will have access only to the same files as the
terminal emulator has, in an unrooted device.
To simplify usage, there is a script
rsync_daemon.sh that starts
the daemon as above, with a port number taken from
solunar is a command-line utility for displaying sunrise,
sunset, moon phase, and related data, for specific locations.
For more information,
see here. Please note that, when using
times other than GMT/UTC,
solunar is only as accurate as the platform's underlying ability
to handle timezone conversions. This is something of an unknown with
The complete build of
vim, including syntax highlight files,
tutorial, etc. This is quite a large package by mobile device standards.
vim does not replace
vi, so you'll need
to run it as
vim explicitly. You can put startup commands in
$HOME/.vimrc in the usual way.
KBOX works by providing the base distribution of utilities
packed into an archive, such that the archive is installed along with the
Java terminal app. The terminal app runs a script which either exec's
bash in the usual way, or unpacks the whole distribution
if this is the first
session. The compressed archive remains in place — it can't be deleted
as it's considered to be part of the app's code — but is largely useless
after first run. However, it does make it possible to reset the base
distribution to defaults if it gets completely broken — there is a
reinstall_kbox.sh that will do this.
Add-on packages are provided in Debian package format, because
busybox happens to include support for that format. Inside the package the
file locations are as in conventional Linux — that is, rooted at
'/'. The busybox packager manager has been extensively hacked to
account for the unconventional file layout
KBOX is forced
When the terminal session starts, the environment variable
is set to point to the root of the KBOX filesystem. Nearly all the modified
utilities make use of this variable to find files.
Shared objects are stored in
$KBOX/usr/lib, and the
variable references this locatin. However, the Android dynamic linker is
a bit peculiar, and some applications do not seem to be able to load
dynamically, while others can, for no obvious difference.
KBOX is open source — usually, but not invariably,
distributed according to the terms of the GNU Public Licence. It is the
work of many authors, over many years. Source code
for my modest contribution
is available on request. Sources for
dropbear, etc., are widely available on the Web. Getting
these things to build for Android was frequently difficult.
If you're struggling with the same thing, please get in touch, and maybe
I can save you some head-beating.
ifconfig segfaults when trying to obtain the settings of the
wifi interface. The Android platform does not expose this information in a
way that is useful to native applications, anyway
- Packages installed using
dpkg cannot be removed, or overwritten
with new versions. This is a limitation of the way I have modified the
utility to work with KBOX, and can probably be fixed
- On some Android versions,
telnetd will not accept incoming connections. This effectively prevents these utilities being used. The problem is that some Android versions simply block incoming connection
packets using the software firewall. In some cases, a workaround is to make
a connection (any kind of connection) from the Android device to the
prospective client's IP number — this seems to fool the wirewall into opening. This isn't a very satisfactory workaround but, sadly, the problem lies in
- Early versions of Klaus Weidner's 'Hacker's Keyboard' do not work very well with later versions of KBOX. For example, some of the special keys do not
generate any input. The solution is to upgrade the keyboard app
Added glulxe and kcalc
Added Perl package
Incorporated version 1.0.48 (latest available) of Jack Palevich's terminal
Updated base package, to fix missing