TokForge Terminal: User Guide (first version)

What it is · Turning it on · The terminal screen · What you can run · Internet · Scripts and files · Using it from chat · Stopping · What it cannot do · Troubleshooting · Privacy · FAQ

What it is

The terminal is a small command shell inside TokForge. You can type commands yourself on the terminal screen, or ask the chat assistant to run a command for you. You approve every command the assistant wants to run.

What it is

• A command shell that works in its own scratch folder inside TokForge.
• Its tools come with the app: the standard toybox command set and curl (for web requests over HTTPS). Commands the phone's own shell provides may also work; expr worked in our tests.
• Off by default. It stays off until you turn it on, and it only turns on where your phone passes its own safety check.

What it is not

• Not a full Linux system. There is no package manager, so you cannot install programs (no apt, pip, git or similar).
• It never downloads a program and runs it. Its tools come with the app.
• It cannot reach your chats, settings or other app data. In the app's own words: "It cannot read your chats, settings or other app data, and it has no internet unless you allow it. Its tools come with the app, so nothing is downloaded and run."
• It cannot reach your phone's shared storage (photos, downloads and so on). Commands that try get "Permission denied".
• It does not run as an administrator (root). It runs as TokForge's own user.

Turning it on

The terminal switch lives in the developer tools, which only show in Advanced mode.

1. Open Settings.
2. At the top, under "Settings Mode", choose "Advanced". (This also turns on the app-wide Advanced switch, so engine names show in the model list.)
3. Open "Connections" (the button reads "Manage connections").
4. Tap "Developer tools (Advanced)" to open that section.
5. Turn on "Terminal (sandboxed)".
6. Wait a moment while the line reads "Checking this phone...". This is the safety check: TokForge makes sure the terminal really is walled into its own folder on your phone before it lets anything run.
7. When the check passes you see "This phone passed the safety check.", an "Open terminal" button, and the line "The assistant can run commands here when you ask, and it asks you before each one."

Below the main switch is "Allow internet in the terminal". Leave it off unless you need it (see "Internet" below).

If the check does not pass, you see "Terminal is not available on this phone:" followed by a reason, and a "Check again" button. Nothing runs on that phone. The reasons you may see:

• "this phone cannot set up the walls that keep the terminal in its own folder" (this is what Android 11 phones show)
• "this phone does not let the terminal tools start"
• "the app could not open a terminal window on this phone"
• "the safety check found that the terminal could reach app data it must not see, so it stays off"
• "the safety check took too long to finish"
• "the safety check stopped with an unexpected error"
• "this version of the app does not include the terminal tools for this phone"

Android 11 phones cannot run the terminal in this version. Newer Android versions passed the check on the Android 15 and 16 phones we tested.

The safety check runs again by itself after an app update or a system update. If the terminal was on, you do not need to do anything.

Turning "Terminal (sandboxed)" off ends any terminal session that is still running, and the assistant can no longer offer to run commands.

If you set "Settings Mode" back to "Basic" later, the terminal stays on and the assistant can still offer commands, but the developer tools section, with "Open terminal" and the internet switch, only shows in Advanced mode.

The terminal screen

Open it with "Open terminal" in Settings (Connections, then "Developer tools (Advanced)").

• "Start" opens a new shell. Then tap the terminal area to bring up the keyboard and type.
• "Restart" closes the current shell and opens a fresh one. Use it after you change "Allow internet in the terminal", because that setting only applies to a new session.
• "Stop everything" ends the shell and every command it started, including commands left running in the background. It then reports "Stopped in ... ms, nothing left running". If it ever says some processes are still running, turn the "Terminal (sandboxed)" switch off, which also ends the session.
• The status line shows how the terminal is protected and whether it has internet, for example "Protection: system call guard · Internet: off". Some phones may show "Protection: Landlock folder rules" instead; both keep the terminal in its own folder.
• When nothing is running it reads "Not running. Tap Start, then tap the terminal to type." When the shell has closed (for example after you type exit) it reads "The shell has ended. Tap Restart to open a new one."

The extra key row above the keyboard

• "Ctrl" is sticky: tap Ctrl, then a letter. Ctrl then c is the same as Ctrl+C.
• "Esc" and "Tab".
• The four arrow keys.
• "^C" stops the running command (Ctrl+C).
• "^D" sends end of input (Ctrl+D). At an empty prompt it closes the shell.
• Swipe the key row sideways to reach ^C, ^D and the symbol keys | ~ / -.

Good to know

• A session keeps running when you leave the terminal screen. "Stop everything" or the Terminal switch ends it.
• Text colors are not shown. Bold, underline and reversed text are.
• Turning the phone or resizing does not re-flow lines that are already on screen.

What you can run

The shell is the phone's standard shell with TokForge's toybox tools first in line. The toolbox includes, among others:

• Files and folders: ls, cat, head, tail, find, mkdir, rm, cp, mv, tar, gzip
• Text: grep, sed, sort, uniq, wc, cut, tr, xargs
• Small tools: sha256sum, base64, date, printf, echo, sleep
• Phone facts: uname -a, id, nproc, uptime, df -h
• Web requests (only with internet on): curl

Used on our test phones: uname -a, id, nproc, uptime, ls -la, cat, printf with sort and uniq -c, sha256sum, date -u, base64, df -h, sleep with Ctrl+C, background jobs, expr in a script, and curl to an HTTPS site.

awk and expr are not in TokForge's own toolbox. Commands the phone's own shell provides may also work; expr worked in our tests.

Pipes and redirection work as usual, for example:

printf "b\na\nb\n" | sort | uniq -c
echo hello | sha256sum
date -u

Job control works: "&" sends a command to the background, "jobs" lists them, "fg" brings one back, and Ctrl+C stops the one in front.

Your scratch home folder

• Every session starts in the terminal's own home folder. It holds two folders of its own, bin and tmp. Everything you create goes here.
• Files you create stay there between sessions and after you close the app. Commands the assistant runs from chat use the same folder, so you can open the terminal and look at what they made.
• Uninstalling TokForge or clearing its app data removes the folder.

Some things Android does not let apps see, so they fail in the terminal too. For example, df does not list your phone's user storage, so it cannot tell you how much free space your phone has. Use the phone's own Settings > Storage for that.

Internet

The terminal has no internet unless you allow it.

1. In Settings, open "Connections", then "Developer tools (Advanced)".
2. Turn on "Allow internet in the terminal". The note under it reads "Also applies to commands the assistant runs. Takes effect when the next terminal session starts."
3. Go back to the terminal and tap "Restart". The status line now reads "Internet: on".

With internet on

• curl works with web addresses by name, including HTTPS. Example: curl -sS https://example.com
• ping does not work. That is on purpose: the terminal only allows normal web-style connections. Use curl to check that a site answers.
• The toybox nc and wget tools cannot look up names. Use curl.
• The terminal cannot connect to TokForge's own control port (the Developer API server). Those connections are refused on purpose, even with internet on.

With internet off, curl stops at once with "curl: (6) Could not resolve host".

Scripts and files

Write files with echo or printf:

echo "shopping: milk eggs" > notes.txt
echo "bread" >> notes.txt
printf 'echo Start\necho Done\n' > hello.sh

">" writes a new file (or replaces it), ">>" adds to the end. In printf, \n starts a new line.

Run a script with sh:

sh hello.sh

Why ./hello.sh fails: Android does not let an app run files from its own writable storage. Even after chmod +x, ./hello.sh stops with "can't execute: Permission denied" (exit code 126). sh hello.sh reads the same file and works.

Why here-documents fail: commands like cat <<EOF ... EOF need a temporary file the shell is not allowed to create here. They stop with "can't create temporary file : Permission denied". Write the file with echo or printf instead. (Run from chat, the card can still show exit code 0 when a later command in the same line succeeded, so read the output, not just the code.)

Files stay between sessions. Open the terminal later and ls -la shows everything you or the assistant wrote.

Using it from chat

When the terminal is on and your phone passed its check, the chat assistant can run one command for you. It always asks first.

How to ask

• Say it plainly with a run word or name the terminal. These worked in our tests:
  "What Linux kernel version is this phone running? Run uname -a to check."
  "Add a sixth item about backups to plan.md in the terminal and show the file again."
• If a request names no command, has no run or execute word, and does not mention the terminal, the assistant answers without running anything. "Create a markdown file plan.md" got no command; "Create a markdown file plan.md in the terminal" did.

The "$ command" shortcut

• Type a line that starts with "$ ", for example "$ uptime", and send it. TokForge skips the model and goes straight to the approval with that exact command. A message that is only a code block, or "run command", works the same way. You still approve it.

The approval dialog

• Title "Run this command?", then "The assistant wants to run this command on your phone:" and the exact command, word for word. Read it before you approve; small models sometimes propose a wrong command.
• Then "It runs in the app's private terminal sandbox. Internet is off." (or "Internet is on.")
• If your chat model is a remote model (Remote API), an extra line says "The command output will be sent to your remote model."
• Buttons: "Run" and "Don't run".

The 60 second rule

• If you do not answer within 60 seconds, the command does not run.
• A system pop-up on top of the dialog (for example a permission prompt) no longer uses up that minute.
• A command the assistant runs is stopped after at most 60 seconds.

What you see after Run

• A "Ran a command" card under the reply, with the command and how it ended: "Finished with exit code ..." (0 means success), "Stopped after ... s", "Stopped by signal ..." or "Ended".
• Tap "Show output" to see what the command printed ("Hide output" folds it again). "No output" means it printed nothing. "Output shortened" means the output was very long, so the card keeps its start and end.
• The card is saved with the message.

What you see after Don't run, or no answer:

• A line "Command not run: you chose Don't run" or "Command not run: no answer in 60 s" appears before the model replies, and the model is told the command did not run.

What the model is told

• Before it picks a command, the model is told the terminal's limits: the folder keeps its files, scripts run with sh, here-documents do not work, there is no internet unless you turned it on, df cannot see your storage, and each turn runs one command.
• After a command runs, the model gets the output marked as command output, with a note that names the one command that ran ("Only this command ran") and tells it not to claim anything else.

One command per turn

• Each message can run one command. To do more in one go, the assistant joins steps with && (for example write a file and run it). For a second command, send another message.
• When a message gets a command offer, web search does not run for that same message.
• If TokForge has to retry a reply that only repeated your message, it does not ask you or run the command a second time.

Agents do not get this tool: in 1.3.8, commands run from chat only. The three Agents presets and the other agents cannot run terminal commands.

Stopping

• Ctrl+C (the "^C" key, or Ctrl then c) stops the command that is running now. The shell stays open and the prompt comes back (it shows 130, the code for "interrupted").
• "Stop everything" ends the whole shell and everything it started, including background jobs. Use it when you are done, or when something will not stop.
• In chat, the chat's Stop button also stops a command the assistant is running.
• Turning off "Terminal (sandboxed)" ends any session.

What it cannot do

• Install packages or programs.
• Download a program and run it.
• Read TokForge's chats, settings or data, or other apps' data.
• Read your phone's shared storage (photos, downloads).
• Run a script file directly (./script.sh). Use sh script.sh.
• Use here-documents (cat <<EOF). Use echo or printf.
• ping, even with internet on.
• Look up web names with nc or wget. Use curl.
• Reach TokForge's own control port.
• Show text colors.
• Run on Android 11 phones.
• Run commands from agents.
• See your phone's free storage with df.
• Run as root.

Troubleshooting

"The terminal is off or not available on this phone."

• You see this on the terminal screen when the switch is off or the safety check did not pass. In Settings, choose "Advanced" under "Settings Mode", open "Connections", then "Developer tools (Advanced)", and turn on "Terminal (sandboxed)".

I cannot find "Developer tools (Advanced)".

• It only shows when "Settings Mode" is set to "Advanced". Then tap its header to open it.

"Terminal is not available on this phone: ..."

• Read the reason. Tap "Check again" once. If it still fails, the terminal cannot run on that phone, and Android 11 phones always show this.

A command runs slowly or seems stuck.

• Some commands take a while or wait for input. Press ^C to stop it.
• A network command with internet off fails at once; with internet on it waits for the website.
• From chat, a command is stopped after at most 60 seconds and the card says "Stopped after ... s".
• The first command after an app or system update first runs the safety check again, so it takes a moment longer.

The assistant did not offer to run anything.

• Check that "Terminal (sandboxed)" is on and the phone passed the check.
• Use a run word, put the command in backticks, add "in the terminal", or type "$ " and the command yourself.

A Run dialog appeared when I did not ask for a command.

• A sentence that starts with a command word (for example "Echo is a great band") can make TokForge offer the tool, and a small model may then propose a command. Tap "Don't run"; nothing runs.

The model proposes a wrong command.

• You always see the exact command first. Tap "Don't run". Then type the right one yourself with "$ ", or ask again and name the command. Example: one small model proposed just a file name, which is not a command, instead of cat followed by that file name.

The model says it ran something that did not run, or the answer does not match the output.

• Trust the card, not the reply. No "Ran a command" card means nothing ran in that turn.
• A reply that shows "command output" without a card is made up.
• Even with a correct card, a small model can misread the output (for example read the wrong line of df). Tap "Show output" and check.

The card shows exit code 0 but the output shows an error.

• The exit code belongs to the last command in the line. A here-document error followed by a working cat still ends with 0. Read the output.

A script fails with exit code 126.

• Run it with sh script.sh instead of ./script.sh.

The "Ran a command" card disappeared.

• In 1.3.8 the card is lost when you tap Regenerate or switch to another version of the reply.

HyperOS warning lines.

• On Xiaomi phones with HyperOS, two system warning lines used to appear in the terminal and in command output. 1.3.8 removes exactly those two lines. Any other line is left as it is.

Privacy

• The terminal works on your phone. Commands you type and their output stay on your phone.
• Nothing leaves the phone unless you allow it:
  • With "Allow internet in the terminal" on, a command you run (or approve) can reach the website it names, like any web request.
  • With a remote model set up (Remote API), approved command output is sent to that server, and the approval dialog says so.
• From the TokForge privacy policy at tokforge.ai/privacy: "If you connect a remote API endpoint you choose, the output of commands you approve in the terminal is sent to that endpoint. If you also turn on the terminal's internet setting, a command you approve can use the internet itself."
• The terminal cannot read your chats, settings, other app data or your phone's shared storage.

FAQ

Is the terminal on by default?

No. It stays off until you turn it on, and only works where your phone passes its safety check.

Can the assistant run commands without asking me?

No. Every command needs your "Run". No answer within 60 seconds means it does not run.

Can it see my photos, files or chats?

No. It is walled into its own scratch folder. Your chats, settings, other app data and shared storage are out of reach.

Can I install Python, git or other tools?

No. There is no package manager, and TokForge never downloads programs to run.

Do my files stay?

Yes. Files in the terminal's home folder stay between sessions until you uninstall TokForge or clear its data.

Does it keep running if I leave the screen?

Yes, a session keeps running. Tap "Stop everything" or turn the switch off to end it.

Why does my Android 11 phone say it is not available?

Android 11 phones cannot set up the walls that keep the terminal in its own folder, so the terminal stays off there.

Can agents use the terminal?

Not in 1.3.8. Commands run from chat only.

Does it work with a remote model?

Yes. The approval dialog then adds "The command output will be sent to your remote model."

Why does ping not work?

The terminal only allows normal web-style connections, even with internet on. Use curl to check that a site answers.

Why did ./myscript.sh fail with "Permission denied"?

Android does not let apps run files from their own storage. Use sh myscript.sh.

Get 1.3.8

To get 1.3.8 from Google Play, open the TokForge listing and join the beta there. The Discord APK is the same version. Everyone else stays on 1.3.6.1, the Play production version.

Important: do not install an older TokForge (1.3.4.1 or earlier) over 1.3.8. It will not open, and the only way back is to uninstall, which erases your chats and settings.

The full list of changes is in the 1.3.8 changelog.