# Deputy Shell — Full Reference Generated file — do not edit directly. This file is produced by `tools/build_docs.py` from `docs-src/content.py`, the canonical Bibliothek content source, and reflects the complete content of every published article. Regenerate with `python tools/build_docs.py` after any content change; edits made here are discarded on the next rebuild. ## Deputy Shell Deputy Shell is a native Android terminal and project workspace designed for coding-agent workflows. It combines persistent terminal sessions, project workspaces, a curated development runtime and mobile-friendly controls in one application. Deputy Shell runs locally on the device. Network-capable tools and services communicate externally only when their operation requires it or when the user instructs them to do so. ## Release status Deputy Shell is pre-release (closed alpha) software, version 0.13.0-alpha.1. Capabilities described in this document as "planned," "under evaluation," or similar are not yet available in the current release — do not report them as shipped. Each article below states its own current feature status, applies-to version, and last-verified date. ## Start Here ### What is Deputy Shell? - Canonical URL: https://deputyshell.com/docs/what-is-deputy-shell/ - Category: Start Here - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: overview, android terminal, coding workspace Deputy Shell is a native Android app that gives you a terminal, project workspaces, and persistent sessions for coding-agent workflows, plus an optional integration with OpenAI's Codex CLI. It runs locally on your device: your projects, sessions, and terminal history live in the app's own storage, and network-capable tools only reach the network when their job requires it or when you tell them to. #### What it is - An Android terminal with persistent sessions you can leave and come back to. - A project/workspace model that keeps separate codebases in separate folders. - A curated, Android-compatible development runtime: Git, Python and pip, Node.js and npm, curl, OpenSSH tools, and ripgrep, delivered as a one-time download. - An optional integration with the Codex CLI, OpenAI's coding agent, for users with their own eligible OpenAI account. #### What it is not - **Not a cloud-hosted coding environment.** Deputy Shell does not host your workspace remotely or provide its own account/cloud-storage system. - **Not "a Deputy Shell AI model."** Deputy Shell does not train or operate its own language model; Codex is OpenAI's product, used with your own OpenAI account. - **Not an OpenAI subscription.** Deputy Shell does not sell, provide, or resell OpenAI accounts, credits, or subscriptions. - **Not a finished Android IDE or full Linux distribution.** There is no integrated code editor, no Android build/APK toolchain yet, and no general package manager — see [Known Limitations](https://deputyshell.com/docs/known-limitations/). Deputy Shell is currently pre-release (closed alpha) software, version 0.13.0-alpha.1. Every article in this Bibliothek states whether the feature it describes is available today, limited, experimental, or still planned. Related articles: - [Getting Started](https://deputyshell.com/docs/getting-started/) - [Requirements](https://deputyshell.com/docs/requirements/) - [Codex on Android](https://deputyshell.com/docs/codex-on-android/) ### Getting Started - Canonical URL: https://deputyshell.com/docs/getting-started/ - Category: Start Here - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: onboarding, first run, setup On first launch, Deputy Shell downloads its development runtime, then opens on the **Default Workspace** with an empty session list. From there you can start working immediately or create a dedicated project first. > **Warning:** Deputy Shell provides a terminal and development workspace. Commands and agents (including Codex) can modify or delete files and communicate with external services. Review actions before approving them, and keep independent backups of anything important. #### First run, step by step 1. **Runtime setup.** The app downloads and verifies its development runtime (roughly 500 MB) over Google Play. See [Runtime Setup](https://deputyshell.com/docs/runtime-setup/) for what happens during this step and how to recover from an interruption. 2. **Choose your privacy settings.** A first-run dialog lets you choose whether to share crash reports and usage statistics, share crash reports only, or share nothing. Nothing is shared unless you choose to. See [Privacy and Telemetry](https://deputyshell.com/docs/privacy-and-telemetry/). 3. **Start in the Default Workspace, or create a project.** The Default Workspace is always available and cannot be deleted. If you're working on something specific, create a named project first — see [Projects and Workspaces](https://deputyshell.com/docs/projects-and-workspaces/). 4. **Start a session.** Use "+ New Session" to open a terminal in the current project. Sessions keep their identity and recent output even if you leave the app. 5. **Optionally sign in to Codex.** Codex is bundled but optional to use. Signing in requires your own eligible OpenAI account — see [Codex Sign-In](https://deputyshell.com/docs/codex-sign-in/). #### Safety and backups Approve agent and command actions only after reviewing what they will do. Deputy Shell is pre-release software: keep independent backups of anything you can't afford to lose, and use [workspace export](https://deputyshell.com/docs/exporting-workspaces/) regularly for anything important. Related articles: - [Runtime Setup](https://deputyshell.com/docs/runtime-setup/) - [Requirements](https://deputyshell.com/docs/requirements/) - [Projects and Workspaces](https://deputyshell.com/docs/projects-and-workspaces/) - [Codex Sign-In](https://deputyshell.com/docs/codex-sign-in/) ### Requirements - Canonical URL: https://deputyshell.com/docs/requirements/ - Category: Start Here - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: requirements, android version, arm64, device compatibility Deputy Shell requires Android 14 or later on a 64-bit ARM device. It has not been broadly validated across the wide range of Android hardware, and support is expanding gradually rather than claimed for "all Android devices." #### Android version - **Minimum:** Android 14 (API level 34). - **Target/built against:** Android 16 (API level 36). #### Architecture Deputy Shell currently requires a device whose **primary** CPU architecture is `arm64-v8a` (64-bit ARM). Devices with a different primary architecture are rejected with a clear "unsupported device" message before any runtime download starts, rather than failing partway through setup. #### Physical device vs. emulator Full command execution (Git, Python, Node.js, curl, ripgrep, and Codex) has been validated on a physical Samsung Galaxy S23 Ultra running Android 14. Android emulators (which typically run on x86_64) can be used to check installation and the user interface, but they cannot run Deputy Shell's ARM64 development runtime at all — the app's own architecture check will report the device as unsupported on such an emulator. #### 16 KB memory page-size devices Newer Android devices may use a 16 KB memory page size instead of the traditional 4 KB. Deputy Shell's packaging has been verified to meet the 16 KB alignment requirements, but it has not yet been run on a physical 16 KB-page-size device — this remains under evaluation. #### Storage and network - Expect roughly 500 MB of download for the initial runtime setup, and more on-device space once it's extracted. - A network connection is required for initial setup, for update checks, and for Codex. Core terminal and file features work offline once setup is complete. Related articles: - [Runtime Setup](https://deputyshell.com/docs/runtime-setup/) - [Getting Started](https://deputyshell.com/docs/getting-started/) - [Known Limitations](https://deputyshell.com/docs/known-limitations/) ### Runtime Setup - Canonical URL: https://deputyshell.com/docs/runtime-setup/ - Category: Start Here - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: runtime, play feature delivery, first run, setup Deputy Shell ships as a small base app and downloads its development runtime — Git, Python, Node.js, curl, OpenSSH tools, ripgrep, and the Codex CLI — the first time you launch it, using Google Play's on-demand module delivery. #### Why it's downloaded separately The full development runtime is large (roughly 500 MB compressed, over 1 GB once extracted). Rather than bundling all of it into the installable app, Deputy Shell requests it as four Play-delivered modules on first run, so the initial app download stays small. #### What the runtime contains - **Core module:** shell and core utilities, Python, and shared runtime metadata. - **Tools module:** Git, curl, SSH/SCP/SFTP, ripgrep, and related command-line tools — the largest of the four modules. - **Node module:** Node.js and npm. - **Codex module:** the Codex CLI, built for Android. #### What you'll see during setup A full-screen setup view shows progress through distinct phases — initializing, downloading, installing, verifying, and starting the terminal — with a percentage based on completed steps, not just elapsed time. If setup fails partway, Deputy Shell shows a plain-language error with the option to retry. #### Current status The Play-delivered download mechanism itself is implemented and has passed local testing. End-to-end delivery through a live Google Play release, including recovery from an interrupted download after a fresh install, is still under evaluation — this is one of the things closed-alpha testing is expected to confirm. #### Updates An application update or a runtime-version change can replace the runtime directory. If you've made manual changes inside the runtime yourself, expect those to be reset by an update — modifying runtime files directly is unsupported and done at your own risk. Related articles: - [Requirements](https://deputyshell.com/docs/requirements/) - [Getting Started](https://deputyshell.com/docs/getting-started/) - [Included Development Tools](https://deputyshell.com/docs/included-development-tools/) - [Troubleshooting Runtime Setup](https://deputyshell.com/docs/troubleshooting-runtime-setup/) ## Projects and Workspaces ### Projects and Workspaces - Canonical URL: https://deputyshell.com/docs/projects-and-workspaces/ - Category: Projects and Workspaces - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: projects, workspaces, default workspace, agents.md A **project** in Deputy Shell is a sidebar entry with its own name that points to a dedicated **workspace** folder on your device. Projects keep separate codebases separate: each one has its own folder, and the sessions you start "in" a project are grouped under it in the sidebar. #### Default Workspace Deputy Shell always has a project called **Default Workspace**. It maps to a fixed folder and cannot be deleted — if you try, Deputy Shell keeps it and shows a message explaining that it can't be removed. It's the natural place to start if you don't need separate named projects yet. #### Projects and sessions Sessions belong to whichever project they were created in, and are grouped by project in the sidebar. A session's actual terminal location (its working directory) is normally the project's workspace folder, but the two can drift apart if a session is moved between projects — see [Workspace Mismatch Warning](https://deputyshell.com/docs/workspace-mismatch-warning/). #### Why exports are project-scoped [Workspace export](https://deputyshell.com/docs/exporting-workspaces/) always exports one project's workspace folder — not whatever folder a session's terminal happens to be sitting in at the time. This keeps export behavior predictable even if a session has drifted from its assigned project. #### Workspace guidance for coding agents Deputy Shell seeds a curated AGENTS.md into a workspace when the file is missing or still contains the retired one-line placeholder. The file explains Deputy Shell's Android/Bionic environment, workspace boundaries, available tools, credential safety, dependency rules, lifecycle constraints, and other guidance for coding agents. Existing non-placeholder AGENTS.md content is preserved, and the seeded file includes a section for project-specific instructions. Related articles: - [Managing Projects](https://deputyshell.com/docs/managing-projects/) - [Sessions](https://deputyshell.com/docs/sessions/) - [Importing Projects](https://deputyshell.com/docs/importing-projects/) - [Exporting Workspaces](https://deputyshell.com/docs/exporting-workspaces/) ### Managing Projects - Canonical URL: https://deputyshell.com/docs/managing-projects/ - Category: Projects and Workspaces - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: projects, rename, delete #### Create a project Use "+ New Project" from the sidebar. Deputy Shell requires an explicit, non-duplicate name — it does not auto-generate placeholder names like "Project 1," so pick a name before creating one. #### Rename a project Renaming a project changes its display name in the sidebar. There is also an optional action to rename the underlying workspace folder to match. That folder rename is blocked while the project has sessions assigned to it or while an import/export is running for that project, and it fails safely — without losing any data — if a folder with the destination name already exists. #### Delete a project Deleting a non-default project removes only its sidebar entry. **The workspace folder and its files are not deleted** — they remain on your device's storage. Any sessions that belonged to the deleted project become "ungrouped" and show a notice explaining that their workspace files remain on disk even though the project entry is gone. Deletion is blocked while an import or export is actively running for that project. > **Warning:** The [Default Workspace](https://deputyshell.com/docs/projects-and-workspaces/) cannot be deleted. Related articles: - [Projects and Workspaces](https://deputyshell.com/docs/projects-and-workspaces/) - [Importing Projects](https://deputyshell.com/docs/importing-projects/) - [Exporting Workspaces](https://deputyshell.com/docs/exporting-workspaces/) ## Sessions and Terminal ### Sessions - Canonical URL: https://deputyshell.com/docs/sessions/ - Category: Sessions and Terminal - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: sessions, terminal, state A session in Deputy Shell is an independent terminal: its own process, its own input and output, and its own retained history. You can run several sessions at once without their output mixing together, and a Codex session is simply a normal terminal session running the `codex` command — it has no special isolation of its own. #### Session states - **Running** — the terminal process is live. - **Stopped** — you (or "Stop All") ended the live process, but the session record, its workspace, and its recent output remain. - **Needs resume** — the process disappeared unexpectedly (for example, after the app or device restarted) and needs to be started again to continue. - **Crashed** — the process exited on its own, unexpectedly. Deleting a session is a separate, further step from stopping one — see [Managing Sessions](https://deputyshell.com/docs/managing-sessions/) for the distinction. #### What's retained across restarts Deputy Shell stores up to approximately 1 MB of recent terminal context per session. When that limit is exceeded, older content is trimmed and the newest portion is retained. This is a bounded recent-context buffer, not a complete or unlimited terminal transcript — and it's excluded from backups, diagnostics exports, and workspace exports. Deleting a session removes this retained context permanently. Related articles: - [Managing Sessions](https://deputyshell.com/docs/managing-sessions/) - [Moving Sessions Between Projects](https://deputyshell.com/docs/moving-sessions/) - [Background Sessions and Notifications](https://deputyshell.com/docs/background-sessions/) - [Terminal Controls](https://deputyshell.com/docs/terminal-controls/) ### Managing Sessions - Canonical URL: https://deputyshell.com/docs/managing-sessions/ - Category: Sessions and Terminal - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: sessions, stop, delete, pin Each session's menu in the sidebar offers: **Rename**, **Pin**/Unpin, **Move** (to a different project — see [Moving Sessions](https://deputyshell.com/docs/moving-sessions/)), **Stop terminal**, and **Delete session**. #### Stop vs. delete These are two different, deliberately separate actions: - **Stop terminal** ends the live process, but keeps the session in the sidebar along with its workspace and recent output. You can come back to it later. - **Delete session** permanently removes the session record and its retained history. This cannot be undone. #### Stop All Active Sessions A single "Stop All Active Sessions" action (with a confirmation dialog, since it can interrupt unsaved terminal work) terminates every currently-running session at once. Each one becomes stopped, not deleted — their history and workspaces remain. #### Pinning Pinning a session keeps it visually distinguished in the sidebar so you can find it quickly among many sessions. Related articles: - [Sessions](https://deputyshell.com/docs/sessions/) - [Moving Sessions Between Projects](https://deputyshell.com/docs/moving-sessions/) - [Background Sessions and Notifications](https://deputyshell.com/docs/background-sessions/) ### Moving Sessions Between Projects - Canonical URL: https://deputyshell.com/docs/moving-sessions/ - Category: Sessions and Terminal - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: sessions, move, projects The "Move" action on a session's menu re-assigns which project it's grouped under in the sidebar. This only changes where the session appears in the list — it does not touch the live terminal process or change its current working directory. #### Why that matters Because moving a session is a sidebar/grouping change only, a session's terminal can end up pointed at a different folder than the project it now appears under. When that happens, Deputy Shell shows a warning on the session — see [Workspace Mismatch Warning](https://deputyshell.com/docs/workspace-mismatch-warning/) for what it looks like, what it means, and how to clear it. #### Deleting a project with active sessions If you delete a project that still has sessions assigned to it, those sessions aren't deleted — they become "ungrouped," with a notice explaining that the project's workspace files remain on disk even though its sidebar entry is gone. This is effectively an automatic move to an unassigned state, with the same mismatch-warning behavior as a manual move. Related articles: - [Managing Sessions](https://deputyshell.com/docs/managing-sessions/) - [Workspace Mismatch Warning](https://deputyshell.com/docs/workspace-mismatch-warning/) - [Projects and Workspaces](https://deputyshell.com/docs/projects-and-workspaces/) ### Workspace Mismatch Warning - Canonical URL: https://deputyshell.com/docs/workspace-mismatch-warning/ - Category: Sessions and Terminal - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: warning, workspace, cwd, moved session If a session's live terminal is sitting in a different folder than the workspace of the project it's currently grouped under, its sidebar card shows an amber **"Running outside project workspace"** warning. #### Why this happens Moving a session between projects (or deleting a project a session belonged to) only changes where the session is grouped in the sidebar — it does not change the terminal's actual current directory. If those two things disagree, Deputy Shell tells you rather than silently letting the mismatch go unnoticed. #### What to do about it Tapping the warning opens a dialog showing the session's current folder and the project's actual workspace folder, along with a ready-to-copy command in the form: ``` cd ~/workspace/projects/ ``` Run that command in the session to move its terminal to match. Once the shell reports it's in the right folder, the warning clears automatically. If you `cd` away again afterward, it can reappear. #### Why it matters for exports [Workspace export](https://deputyshell.com/docs/exporting-workspaces/) always exports the project's assigned workspace folder, not wherever a mismatched session's terminal currently sits — so a mismatch warning is a useful sign to check you're exporting (and working in) the folder you expect. Related articles: - [Moving Sessions Between Projects](https://deputyshell.com/docs/moving-sessions/) - [Exporting Workspaces](https://deputyshell.com/docs/exporting-workspaces/) - [Managing Sessions](https://deputyshell.com/docs/managing-sessions/) ### Background Sessions and Notifications - Canonical URL: https://deputyshell.com/docs/background-sessions/ - Category: Sessions and Terminal - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: background, notification, foreground service While Deputy Shell has a live session, it keeps that session running in the background using Android's foreground-service mechanism, showing an ongoing notification (for example, "Deputy Shell session running," or a count when several sessions are active) with a **Stop Session** action. #### Notification permission Deputy Shell asks for notification permission once, the first time you actually have a live session — not immediately at launch, and not repeatedly. If you decline, your sessions keep running normally; you simply won't see the ongoing-session notification until you enable notifications for the app in Android's Settings. You can always come back to a running session through the app itself. Notification permission currently controls Deputy Shell's ongoing live-session notification. The current release does not send a separate background notification when an agent is waiting at an approval prompt. #### Limits on background survival Android and individual device manufacturers can still stop background app activity — through battery optimization, aggressive task killers, or system-level foreground-service limits. Deputy Shell does not claim sessions survive indefinitely in the background: if the system ends a session's process, that session is marked as needing resume rather than silently pretending it's still running, and its notification is removed. Background reliability has so far been validated primarily on one Samsung device; behavior can vary on other manufacturers' more aggressive battery-management systems. Related articles: - [Sessions](https://deputyshell.com/docs/sessions/) - [Managing Sessions](https://deputyshell.com/docs/managing-sessions/) - [Troubleshooting Sessions and Background Activity](https://deputyshell.com/docs/troubleshooting-sessions/) ### Terminal Controls - Canonical URL: https://deputyshell.com/docs/terminal-controls/ - Category: Sessions and Terminal - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: terminal, keys, touch controls Deputy Shell's terminal includes a togglable two-row accessory key panel so you can reach keys a touchscreen keyboard doesn't normally offer: - **Row 1:** Esc, Tab, Ctrl, Up-arrow, `/`, `-`, Alt - **Row 2:** Home, End, Left-arrow, Down-arrow, Right-arrow, PgUp, PgDn These cover the keys most command-line tools and terminal UIs (like editors and Codex's own interface) expect but a stock Android keyboard doesn't provide directly. #### Current limitation Long-press-to-repeat on these accessory keys (holding a key down to repeat it, the way many hardware keyboards work) is not yet available — each tap sends the key once. Related articles: - [Terminal Search, Copy, and Scrollback](https://deputyshell.com/docs/terminal-search-copy-scrollback/) - [Sessions](https://deputyshell.com/docs/sessions/) ### Terminal Search, Copy, and Scrollback - Canonical URL: https://deputyshell.com/docs/terminal-search-copy-scrollback/ - Category: Sessions and Terminal - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: search, copy, selection, scrollback, ansi #### Search A search panel lets you type a query and jump between matches in the visible and retained terminal output, with Previous/Next buttons and a "result X of Y" counter. #### Selecting and copying text A long press (about half a second) on terminal text starts word-based selection, with drag handles and a magnifier for fine adjustment, plus a floating Copy / Select-all menu. A separate action lets you copy the entire visible screen at once without entering selection mode. Tapping a detected URL (outside of selection mode) opens it in your browser. This selection is **line-based** — it does not yet reflow semantically across resizes the way some desktop terminals do; for most copy/paste use it behaves as expected, but complex multi-line selections spanning a resize may not select exactly what you'd expect. #### Scrolling and jump-to-latest Dragging scrolls the terminal viewport. Once you've scrolled away from the bottom, output no longer auto-follows, and a floating "jump to latest" button appears — it changes appearance if new output has arrived while you were scrolled up. Tapping it snaps back to live output. #### Terminal emulation coverage The terminal supports full-color ANSI output (16-color, 256-color, and true color), cursor movement and editing, and the alternate-screen buffer used by full-screen text apps. It does not yet fully support mouse-tracking terminal apps, clickable OSC hyperlinks, or complete bracketed-paste behavior — most command-line tools work fine, but a small minority of terminal apps that depend on those specific features may behave imperfectly. Related articles: - [Terminal Controls](https://deputyshell.com/docs/terminal-controls/) - [Sessions](https://deputyshell.com/docs/sessions/) ## Codex and Coding Agents ### Codex on Android - Canonical URL: https://deputyshell.com/docs/codex-on-android/ - Category: Codex and Coding Agents - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: codex, openai, coding agent, android Deputy Shell bundles OpenAI's **Codex CLI**, built to run on Android, as part of its development runtime. Codex runs as an ordinary command inside a normal terminal session — there's no separate "Codex session" type with different isolation from any other session. #### Bundled, but optional to use The Codex module downloads as part of Deputy Shell's mandatory first-run setup along with the rest of the runtime — you can't skip downloading it. Actually *signing in and using* Codex, however, is entirely optional: the terminal, projects, and bundled development tools all work without it. #### Account requirements Using Codex requires your own eligible OpenAI account. Deputy Shell does not provide, sell, or resell OpenAI accounts, credits, or subscriptions — availability, usage limits, and any charges are set by OpenAI and depend entirely on your own account and plan, and can change independently of Deputy Shell. #### Network requirements Codex needs live network access to OpenAI's servers for sign-in and for everything beyond basic version/help commands. When you use Codex, your prompts and any project or file content you include in a request may be sent to OpenAI — Deputy Shell does not intercept or separately store that traffic beyond keeping your local sign-in token. #### Not affiliated with OpenAI Deputy Shell is an independent product. It distributes Codex CLI client software; it does not operate OpenAI's hosted service, and is not affiliated with, endorsed by, or a partner of OpenAI. For how to sign in, see [Codex Sign-In](https://deputyshell.com/docs/codex-sign-in/). For how command approvals work, see [Codex Approvals](https://deputyshell.com/docs/codex-approvals/). Related articles: - [Codex Sign-In](https://deputyshell.com/docs/codex-sign-in/) - [Codex and Command Approvals](https://deputyshell.com/docs/codex-approvals/) - [Requirements](https://deputyshell.com/docs/requirements/) ### Codex Sign-In - Canonical URL: https://deputyshell.com/docs/codex-sign-in/ - Category: Codex and Coding Agents - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: codex, sign in, authentication, chatgpt, api key Deputy Shell's guided sign-in path for Codex is **"Sign in with ChatGPT"** — a device-authorization flow that hands off to your browser. Advanced users can instead authenticate with their own OpenAI API key directly through the bundled Codex CLI. #### Guided sign-in: Sign in with ChatGPT 1. Starting sign-in shows a login link. Deputy Shell detects it and opens it automatically in your browser; if that doesn't happen, a tap-to-open option is shown instead. 2. Complete the sign-in with your OpenAI account in the browser, the same way you would on desktop. 3. Return to Deputy Shell — the session reflects that you're signed in once the browser flow completes. This flow requires your own eligible OpenAI account, and a working network connection to reach OpenAI's sign-in servers. > **Warning:** Before your first sign-in, Deputy Shell shows a disclosure explaining what information may be sent to OpenAI as part of using Codex. Read it before continuing. #### Manual API-key login through Codex CLI Available through Codex CLI, with manual setup. End-to-end verified on the current release-candidate runtime. Deputy Shell's guided sign-in uses ChatGPT/device authentication. Advanced users can instead authenticate with their own OpenAI API key through the bundled Codex CLI. Deputy Shell does not currently provide a dedicated API-key settings screen for this — it's a terminal command sequence, not a tap-to-use option. The bundled Codex CLI accepts the key on standard input, not as a command-line argument, so it needs to be piped in: ``` export OPENAI_API_KEY="your-api-key" printenv OPENAI_API_KEY | codex login --with-api-key unset OPENAI_API_KEY codex login status codex ``` 1. Set the environment variable with your key. 2. Pipe it into `codex login --with-api-key`. 3. Remove it from the environment immediately. 4. Confirm with `codex login status`, then start Codex. > **Warning:** OpenAI API usage is billed separately from ChatGPT subscriptions — check your OpenAI account's own billing before relying on this route. > **Warning:** Typing the key directly (for example, in an `export` command) can leave it visible in retained terminal text or shell history. Avoid screenshots or sharing terminal output while it's visible, and unset the variable immediately after signing in. > **Warning:** Never save the key in a project's `.env` file, a script, or anything you might later export or share — [workspace export](https://deputyshell.com/docs/exporting-workspaces/)'s exclusion rules reduce but do not eliminate the risk of a saved key leaking. > **Warning:** Deputy Shell does not provide, manage, or bill for your API key. This authentication route is supplied by the bundled Codex CLI itself, not by a Deputy Shell feature. Related articles: - [Codex on Android](https://deputyshell.com/docs/codex-on-android/) - [Codex and Command Approvals](https://deputyshell.com/docs/codex-approvals/) - [Troubleshooting Codex Sign-In](https://deputyshell.com/docs/troubleshooting-codex-sign-in/) ### Codex and Command Approvals - Canonical URL: https://deputyshell.com/docs/codex-approvals/ - Category: Codex and Coding Agents - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: approvals, safety, guardrails Before certain higher-risk shell commands run — whether you typed them yourself or an agent like Codex proposed them — Deputy Shell can require your explicit approval first. #### What triggers an approval By default, Deputy Shell flags patterns like package installs (`npm install`, `pip install`), piping a downloaded script straight into a shell, `git clone`, making a file executable, running scripts, editing sensitive configuration files, and commands that could expose credentials. Deputy Shell also always blocks attempts to modify its own curated runtime tools directly (for example, trying to upgrade the bundled Node.js or Codex version from inside the terminal) — that only happens through app updates. #### Where approval prompts appear Approval prompts appear inside the active Deputy Shell session, where you review and respond to them directly. The current release does not send a separate background notification alerting you that an agent is waiting for approval — if you've left the app, you'll need to return to the session to see and respond to a pending prompt. #### What to review before approving - What the command or agent action will actually do, not just its stated intent. - Whether it touches files or paths you didn't expect. - Whether it will send data somewhere over the network. #### Your responsibility Agent-generated commands and code can be incorrect. Approving an action means you're choosing to run it — review it the way you would review a command a colleague asked you to run for them, and keep backups of anything you can't afford to lose. Related articles: - [Codex on Android](https://deputyshell.com/docs/codex-on-android/) - [Codex Sign-In](https://deputyshell.com/docs/codex-sign-in/) - [Background Sessions and Notifications](https://deputyshell.com/docs/background-sessions/) - [Included Development Tools](https://deputyshell.com/docs/included-development-tools/) ## Development Tools ### Included Development Tools - Canonical URL: https://deputyshell.com/docs/included-development-tools/ - Category: Development Tools - Feature status: Mixed — see status table below - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: tools, git, python, node, ripgrep, curl, ssh Deputy Shell bundles a curated set of command-line development tools, built to run natively on Android, as part of its downloaded runtime. #### Included and supported | Tool | Version | Notes | | --- | --- | --- | | Git | 2.53.0 | Includes the built-in credential-store and HTTPS remote helpers. | | curl / libcurl | 8.20.0 | | | OpenSSH tools | ssh, scp, sftp | | | Node.js | 22.22.2 | Includes npm and npx. | | npm | 10.9.7 | | | Python | 3.13.13 | Includes pip 26.0.1. | | ripgrep (rg) | 14.1.1 | Built without PCRE2 support — PCRE2-specific regex features are unavailable. | | vim | system-provided | Lightweight in-terminal editing. | #### Planned modular tool packs `jq`, `rsync`, and `nano` have been evaluated but are not currently included — they're candidates for a future tool pack. #### Not currently included - A general package manager (no `apt`, `pkg`, `brew`, or similar). - Full compiler toolchains (no C/C++/Rust/clang, no `make`/`cmake`). - Arbitrary Linux-native networked command-line agents beyond Codex — see [Known Limitations](https://deputyshell.com/docs/known-limitations/). #### Version pinning These tool versions are curated and pinned by Deputy Shell. Attempting to self-update any of them from inside the terminal (for example, upgrading Node.js or pip directly) is detected and blocked — new versions arrive only through app updates. Related articles: - [Git, Python, Node.js, and More on Android](https://deputyshell.com/docs/git-python-node-on-android/) - [Codex and Command Approvals](https://deputyshell.com/docs/codex-approvals/) - [Runtime Setup](https://deputyshell.com/docs/runtime-setup/) ### Git, Python, Node.js, and More on Android - Canonical URL: https://deputyshell.com/docs/git-python-node-on-android/ - Category: Development Tools - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: git, python, pip, node, npm, ssh, curl, ripgrep, android Deputy Shell's development runtime brings a working command-line toolchain to Android without requiring you to assemble one yourself: Git for version control, Python with pip, Node.js with npm, curl and OpenSSH for network access, and ripgrep for fast searching across a project — see [Included Development Tools](https://deputyshell.com/docs/included-development-tools/) for exact versions. #### What this is good for - **Cloning and pushing with Git** over HTTPS or SSH, using the same credential flows you'd use on desktop. - **Running Python scripts and installing packages with pip** for scripting, data tasks, or small tools. - **Running Node.js tools and npm packages** for JavaScript/TypeScript projects, CLIs, and build scripts that don't require native compilation. - **Fetching things with curl** and connecting to remote hosts with SSH/SCP/SFTP. - **Searching a project instantly with ripgrep**, including from inside a Codex session. #### What this isn't Deputy Shell is not a full desktop Linux distribution. There's no general package manager, no C/C++/Rust compiler toolchain, and self-updating any of the bundled tools from inside the terminal is blocked — see [Included Development Tools](https://deputyshell.com/docs/included-development-tools/) for the full breakdown of what's supported, planned, and not included. #### Working with Codex Because these tools live in the same terminal environment Codex runs in, Codex can call Git, ripgrep, Node.js, or Python directly as part of completing a task — subject to the same [approval prompts](https://deputyshell.com/docs/codex-approvals/) as if you'd typed the command yourself. Related articles: - [Included Development Tools](https://deputyshell.com/docs/included-development-tools/) - [Codex on Android](https://deputyshell.com/docs/codex-on-android/) - [Projects and Workspaces](https://deputyshell.com/docs/projects-and-workspaces/) ## Files, Imports and Exports ### Importing Projects - Canonical URL: https://deputyshell.com/docs/importing-projects/ - Category: Files, Imports and Exports - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: import, zip, document picker From a project's menu, "Import into this workspace" opens Android's system document picker so you can bring an existing ZIP archive or file into that project's folder. #### What happens on import - Selecting a **.zip** file merge-imports it: files inside the archive are added or overwritten, and files already in the workspace that aren't in the archive are left untouched. - Selecting a non-zip file imports it as a single file into the workspace. - If any filenames would be overwritten, Deputy Shell scans for those conflicts first and asks you to confirm before touching any existing files. #### Path safety Before extracting anything, every entry in the archive is checked: no absolute paths, no path-traversal ("..") segments, and no unreasonably long names are allowed. Imports are also capped in size — roughly 2,000 files, 100 MB total, and 25 MB per single file — to keep a malformed or oversized archive from causing problems. #### If Deputy Shell closes mid-import Imports run as a tracked, step-by-step operation. If the app is closed or crashes partway through, the next time you open Deputy Shell it automatically rolls back any partially-written files, or keeps the import if it had already finished completely — your workspace is never left half-written. #### Limitations - Only one import or export can run against a given project at a time; a second attempt shows a busy message. - The document picker isn't restricted to `.zip` at the file-choosing step — pick carefully. **Back up anything important before importing over existing work.** Related articles: - [Managing Projects](https://deputyshell.com/docs/managing-projects/) - [Exporting Workspaces](https://deputyshell.com/docs/exporting-workspaces/) - [Interrupted Export Recovery](https://deputyshell.com/docs/export-recovery/) ### Exporting Workspaces - Canonical URL: https://deputyshell.com/docs/exporting-workspaces/ - Category: Files, Imports and Exports - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: export, zip, workspace "Export workspace zip," available from a project's menu, packages that project's workspace folder into a ZIP file at a destination you choose, using Android's document picker. #### What gets exported Export always covers the **project's assigned workspace folder** — not wherever a session's terminal happens to currently be, which matters if a session has been moved and shows a [workspace mismatch warning](https://deputyshell.com/docs/workspace-mismatch-warning/). #### What's excluded, and why To reduce the chance of accidentally sharing credentials or bulky generated files, exports leave out paths such as `.git`, `.ssh`, agent-authentication and agent-state folders, `node_modules`, build/output directories, `.env` files, and files that look like private keys or contain "auth" or "token" in their path. > **Warning:** This exclusion list reduces risk — it does not eliminate it. It matches known patterns rather than scanning file contents for secrets. **Always review an exported archive yourself before sharing it with anyone.** #### How export works internally Deputy Shell first builds and verifies a complete ZIP in its own private storage, then copies that verified archive to the destination you picked. If that copy step is interrupted, see [Export Recovery](https://deputyshell.com/docs/export-recovery/). #### Limitations Only one import or export can run per project workspace at a time. Related articles: - [Managing Projects](https://deputyshell.com/docs/managing-projects/) - [Interrupted Export Recovery](https://deputyshell.com/docs/export-recovery/) - [Importing Projects](https://deputyshell.com/docs/importing-projects/) - [Local Storage and Data](https://deputyshell.com/docs/local-storage/) ### Interrupted Export Recovery - Canonical URL: https://deputyshell.com/docs/export-recovery/ - Category: Files, Imports and Exports - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: export, recovery, interrupted Deputy Shell builds and verifies a workspace export in its own private storage first, then copies that finished archive to the destination you picked — because not every Android storage provider (cloud drives especially) guarantees that a copy either fully completes or leaves no trace. #### If the copy step is interrupted If Deputy Shell is closed, crashes, or the destination copy otherwise fails to finish, the next time you open the app you'll see a **"Finish workspace export"** dialog with three choices: - **Choose another destination** — retries the copy from the still-valid private archive to a new location. - **Discard export** — deletes the private archive and attempts to clean up the incomplete file at the original destination, if it's still reachable. - **Later** — keeps the private archive and hides the dialog for your current session only; it reappears the next time you open the app. If the private archive itself turns out to be missing, incomplete, or fails its own integrity check, "Choose another destination" and "Later" aren't offered — only **Discard** is available, since there's nothing valid left to retry from. #### Current limitation This recovery flow has been validated through automated crash-simulation testing, but full manual testing across every real storage provider (different cloud-drive apps, forced app termination at different exact moments, device reboots mid-copy) is still in progress. If you hit unexpected behavior during an export, exporting to local device storage first (rather than directly to a cloud-drive provider) is the more thoroughly-tested path. Related articles: - [Exporting Workspaces](https://deputyshell.com/docs/exporting-workspaces/) - [Importing Projects](https://deputyshell.com/docs/importing-projects/) ## Privacy and Diagnostics ### Local Storage and Data - Canonical URL: https://deputyshell.com/docs/local-storage/ - Category: Privacy and Diagnostics - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: storage, local data, backup By default, Deputy Shell keeps everything it creates in the app's own private Android storage: your project and workspace files, project/session names, recent terminal context, your preferences and privacy choices, and any signed-in agent credentials (such as your Codex sign-in). #### Excluded from backup This app-private data is excluded from Android's automatic cloud backup and device-to-device transfer — it stays on the device unless you deliberately move it, for example with [workspace export](https://deputyshell.com/docs/exporting-workspaces/). #### Once you export Files you explicitly export (a workspace ZIP, or a [diagnostics export](https://deputyshell.com/docs/diagnostics/)) leave app-private storage and land at whatever destination you chose — a folder on your device, a cloud-drive app, or wherever else Android's document picker lets you save to. From that point, ordinary Android file permissions and whatever app you saved it to govern that copy, not Deputy Shell. For the full legal privacy statement, see the [Deputy Shell Privacy Policy](https://deputyshell.com/privacy/). Related articles: - [Privacy and Telemetry](https://deputyshell.com/docs/privacy-and-telemetry/) - [Diagnostics Export](https://deputyshell.com/docs/diagnostics/) - [Exporting Workspaces](https://deputyshell.com/docs/exporting-workspaces/) ### Privacy and Telemetry - Canonical URL: https://deputyshell.com/docs/privacy-and-telemetry/ - Category: Privacy and Diagnostics - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: privacy, telemetry, crash reporting, analytics Deputy Shell separates four different kinds of data flow, and it's worth keeping them distinct: #### 1. Local application data Your projects, sessions, and preferences, kept on-device — see [Local Storage and Data](https://deputyshell.com/docs/local-storage/). #### 2. Optional crash and ANR reporting Deputy Shell can optionally report crashes and app freezes (ANRs) to help fix bugs. This is **off by default**. A first-run dialog lets you choose to share crashes and usage statistics, share crash reports only, or share nothing — and Settings has an independent toggle if you want to change your mind later. #### 3. Optional, limited usage statistics Deputy Shell can optionally collect a small set of usage events (like "app ready" or "session created") to understand how the app is used. This is also **off by default** and controlled separately from crash reporting. #### 4. Codex / OpenAI processing When you use Codex, prompts and any project content you include may be sent to OpenAI as part of that request — this is separate from Deputy Shell's own telemetry and is covered in [Codex on Android](https://deputyshell.com/docs/codex-on-android/). #### User-directed network commands Tools like Git, curl, SSH, and package installers can send data over the network when you or an agent instructs them to (for example, pushing to a remote repository) — that's the normal, expected behavior of those tools, not something Deputy Shell adds on top. This page summarizes behavior that's also described in the full [Deputy Shell Privacy Policy](https://deputyshell.com/privacy/), which is the authoritative legal document — read it for complete details. Related articles: - [Local Storage and Data](https://deputyshell.com/docs/local-storage/) - [Diagnostics Export](https://deputyshell.com/docs/diagnostics/) - [Codex on Android](https://deputyshell.com/docs/codex-on-android/) ### Diagnostics Export - Canonical URL: https://deputyshell.com/docs/diagnostics/ - Category: Privacy and Diagnostics - Feature status: Available - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: diagnostics, support, export From Settings, you can create a diagnostics export — a small ZIP file intended to help troubleshoot a problem, without including your actual terminal or project content. #### What it includes A short summary file, a metadata file (app/device/runtime state), a support readme, and a note listing what was deliberately excluded. #### What it deliberately excludes Diagnostics exports are designed to leave out terminal commands and output, workspace/project source content, file paths and project names, and any credentials. #### Nothing is uploaded automatically Creating a diagnostics export is entirely manual, and nothing is sent anywhere on its own. After it's created, Android's normal share sheet opens with [support@deputyshell.com](mailto:support@deputyshell.com) suggested as a recipient — sending it is still your choice. > **Warning:** Review the export yourself before sending it. Never attach passwords, access tokens, API keys, private keys, or confidential project content to a support request. Related articles: - [Privacy and Telemetry](https://deputyshell.com/docs/privacy-and-telemetry/) - [Local Storage and Data](https://deputyshell.com/docs/local-storage/) ## Updates and Compatibility ### Checking for Updates - Canonical URL: https://deputyshell.com/docs/updates/ - Category: Updates and Compatibility - Feature status: Available with limitations - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: updates, google play Deputy Shell checks Google Play for updates automatically each time you bring the app to the foreground, limited to roughly once every 24 hours, and you can also trigger a manual check from Settings at any time. #### Possible states - **Up to date** — nothing to do. - **Offline** — Deputy Shell tells you it needs a connection to check Google Play, rather than showing a generic error. - **Unavailable** — shown on installs that didn't come from Google Play (for example, sideloaded builds), since there's no Play update to check. - **Update available / downloading / ready to restart / failed** — the normal stages of an in-app update. #### What's preserved Your projects, sessions, and sign-in state are designed to survive an update — active sessions become resumable rather than being silently discarded before the update finishes restarting the app. #### Current limitation The full real-world update path — going from one published Play version to the next on a real device — is still under evaluation as part of closed-alpha testing. Related articles: - [Requirements](https://deputyshell.com/docs/requirements/) - [Runtime Setup](https://deputyshell.com/docs/runtime-setup/) ## Troubleshooting ### Troubleshooting Runtime Setup - Canonical URL: https://deputyshell.com/docs/troubleshooting-runtime-setup/ - Category: Troubleshooting - Feature status: Reference - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: troubleshooting, runtime, setup #### Symptom: setup reports "unsupported device" **Likely cause:** your device's primary CPU architecture isn't `arm64-v8a` — this includes most Android emulators, which typically run x86_64. **What to try:** Deputy Shell currently requires a 64-bit ARM Android device; see [Requirements](https://deputyshell.com/docs/requirements/). This isn't something a retry will fix. **Data preserved:** nothing was written yet — no impact on any other app data. #### Symptom: setup is stuck or very slow **Likely cause:** a slow or unstable network connection, or insufficient free storage for the runtime (roughly 500 MB download, more once extracted). **What to try:** check your connection, confirm you have enough free storage, and retry setup using the in-app retry option. **Data preserved:** any projects or sessions from before are unaffected; setup itself hasn't finished so there's nothing to lose there. #### Symptom: setup fails with an error **What to try:** use the in-app "Retry" option first. If it keeps failing, restart the app and try again. **When to export diagnostics:** if retries consistently fail, create a [diagnostics export](https://deputyshell.com/docs/diagnostics/) before contacting support — it captures setup-relevant metadata without your personal content. **When to contact support:** if the same failure persists after a retry and a fresh app restart, reach [support@deputyshell.com](mailto:support@deputyshell.com) with your device model, Android version, and (if you made one) your diagnostics export. Related articles: - [Runtime Setup](https://deputyshell.com/docs/runtime-setup/) - [Requirements](https://deputyshell.com/docs/requirements/) - [Diagnostics Export](https://deputyshell.com/docs/diagnostics/) ### Troubleshooting Codex Sign-In - Canonical URL: https://deputyshell.com/docs/troubleshooting-codex-sign-in/ - Category: Troubleshooting - Feature status: Reference - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: troubleshooting, codex, sign in #### Symptom: the sign-in link doesn't open automatically **Likely cause:** the automatic browser handoff didn't trigger, or your device doesn't have a default browser configured for it. **What to try:** use the tap-to-open option shown alongside the link, or copy the printed URL and open it manually in your browser. **Data preserved:** unaffected — this doesn't touch your projects or other sessions. #### Symptom: sign-in seems stuck after completing the browser step **Likely cause:** a network interruption between your device and OpenAI's sign-in servers, or the browser step wasn't fully completed. **What to try:** confirm you have a working network connection, return to Deputy Shell, and try signing in again from the start. **Data preserved:** your projects and other sessions are unaffected regardless of Codex sign-in status. #### When to contact support If sign-in repeatedly fails with a working network connection, create a [diagnostics export](https://deputyshell.com/docs/diagnostics/) (it excludes credentials and terminal content) and contact [support@deputyshell.com](mailto:support@deputyshell.com) with your device model and Android version. Related articles: - [Codex Sign-In](https://deputyshell.com/docs/codex-sign-in/) - [Codex on Android](https://deputyshell.com/docs/codex-on-android/) - [Diagnostics Export](https://deputyshell.com/docs/diagnostics/) ### Troubleshooting Sessions and Background Activity - Canonical URL: https://deputyshell.com/docs/troubleshooting-sessions/ - Category: Troubleshooting - Feature status: Reference - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: troubleshooting, sessions, background #### Symptom: a session shows "needs resume" **Likely cause:** the underlying process was ended by the system — commonly after the app or device restarted, or Android reclaimed background resources. **What to try:** reopen the session; Deputy Shell will start a new process for it. Its workspace and recent output are unaffected. **Data preserved:** the session's workspace folder and recent retained output remain; only the live process needed restarting. #### Symptom: a background session stops unexpectedly **Likely cause:** Android or your device manufacturer's battery-management system ended the background process. This is more common on devices with aggressive battery optimization. **What to try:** check your device's battery-optimization and background-activity settings for Deputy Shell, and consider exempting it if your device offers that option. **Data preserved:** as above — workspace and recent context remain; the session shows as needing resume. #### Symptom: no ongoing notification appears for a running session **Likely cause:** notification permission was declined, or notifications for Deputy Shell are disabled in Android Settings. **What to try:** enable notifications for Deputy Shell in Android's app settings. The session itself keeps running either way — this only affects whether you see the ongoing notification. #### When to contact support If sessions are ending unexpectedly even with battery optimization disabled for Deputy Shell, export [diagnostics](https://deputyshell.com/docs/diagnostics/) and reach [support@deputyshell.com](mailto:support@deputyshell.com) with your device model and manufacturer. Related articles: - [Sessions](https://deputyshell.com/docs/sessions/) - [Background Sessions and Notifications](https://deputyshell.com/docs/background-sessions/) - [Managing Sessions](https://deputyshell.com/docs/managing-sessions/) ## Limitations and Compatibility ### Known Limitations - Canonical URL: https://deputyshell.com/docs/known-limitations/ - Category: Limitations and Compatibility - Feature status: Mixed — see status table below - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: limitations, compatibility, known issues Deputy Shell is pre-release software. This page documents current restrictions, unsupported workflows and device-validation boundaries in the current release. For intended future direction, see the [Product Roadmap](https://deputyshell.com/roadmap). Roadmap items are not descriptions of features available in the current release. #### Current application limitations - Session actions (stop, delete, move) work one session at a time — there's no bulk multi-select action yet. - Terminal accessory keys don't yet support press-and-hold repeat. - The terminal doesn't yet fully support mouse-tracking apps, complete OSC hyperlink rendering, or complete bracketed paste. - Deputy Shell does not yet send a dedicated background notification when an agent is waiting for approval. #### Android platform limitations - Background terminal sessions are subject to Android's and individual manufacturers' battery and background-activity restrictions — see [Background Sessions](https://deputyshell.com/docs/background-sessions/). - Deputy Shell requires Android 14 or later on a 64-bit ARM (`arm64-v8a`) device — see [Requirements](https://deputyshell.com/docs/requirements/). #### Device-validation limitations - Full command execution has so far been validated on one physical Samsung device. - Devices using the newer 16 KB memory page size pass Deputy Shell's packaging checks but haven't yet been tested on real 16 KB hardware. - Android emulators (typically x86_64) can't run the ARM64 development runtime at all. #### Third-party service limitations Codex requires network access and your own eligible OpenAI account. Its availability, usage limits, and any charges are set by OpenAI, not Deputy Shell, and can change independently. Related articles: - [Can Deputy Shell Build Android APKs?](https://deputyshell.com/docs/can-deputy-shell-build-apks/) - [Requirements](https://deputyshell.com/docs/requirements/) - [Included Development Tools](https://deputyshell.com/docs/included-development-tools/) ### Can Deputy Shell Build Android APKs? - Canonical URL: https://deputyshell.com/docs/can-deputy-shell-build-apks/ - Category: Limitations and Compatibility - Feature status: Planned - Applies to: 0.13.0-alpha.1 (pre-alpha) - Last verified: 2026-07-31 - Tags: apk, android build, roadmap **No, not in the current release.** Deputy Shell currently provides an Android-first terminal and coding-agent workspace. An on-device Android build toolchain, debug APK generation, signing, export, and installation are not available today. #### What this means in practice You can use Deputy Shell's bundled Git, Node.js, and Python to write and manage Android project source code on your device, but there is currently no bundled Android SDK, Gradle build tooling, or APK signing/installation flow inside the app. Building an Android app from a Deputy Shell workspace today means pushing your code to a machine that has the Android build toolchain, the same way you would from any other remote terminal. #### Status Deputy Shell does not currently include the Android SDK, Gradle build tooling or an APK build workflow. The planned direction begins with an optional Android development pack and on-device debug APK builds. Local signing and production release workflows remain a longer-term direction because secure local key storage, backup and recovery still require further design. Direct installation from Deputy Shell is not promised as a guaranteed capability. See the [Android development track on the Product Roadmap](https://deputyshell.com/roadmap#android-development) for the intended direction. Roadmap items are not available in the current release. For the full current-vs-planned picture, see [Known Limitations](https://deputyshell.com/docs/known-limitations/). Related articles: - [Known Limitations](https://deputyshell.com/docs/known-limitations/) - [What is Deputy Shell?](https://deputyshell.com/docs/what-is-deputy-shell/) - [Git, Python, Node.js, and More on Android](https://deputyshell.com/docs/git-python-node-on-android/) ## Related resources - Product Roadmap: https://deputyshell.com/roadmap — current product direction; describes intended direction, not shipped capability. - Release Notes: https://deputyshell.com/releases/ — first-party production release notes.