astrion-website/content/en/05-execution-security.md

# Execution & Security

This chapter covers how Astrion executes AI-initiated actions safely: the actual behavior of sandbox execution, path authorization, and the approval mechanism. For the four conceptual switches (deployment / permission / execution environment / work mode), see the "Core Concepts" chapter first; this chapter focuses on concrete behavior and day-to-day management.

> Scope note: the "live terminal" is just an observation panel and is unrelated to the security mechanisms; see the "Conversation" chapter.

---

## 1. How Commands Are Executed

### run_command: two-phase execution

Take the default recommended `approval` mode as an example. The actual journey of a shell command initiated by the AI is:

1. **It executes first with read-only identity**—can read but not write (host mode relies on the OS sandbox; docker mode relies on a non-privileged user inside the container);
2. If the command does not touch any write operation, the result is returned directly, fully transparent;
3. If it triggers a permission denial (writing files, modifying the system), **it automatically escalates into an approval request to you**;
4. After you approve, **only this one command** is retried with writable identity; if you reject it or the request times out, it is not executed at all;
5. The AI receives only the final result; the intermediate process never disturbs its reasoning.

`auto_approval` mode replaces the approver in step 3 with an auto-approval agent; `unrestricted` mode skips approval and executes directly; in `readonly` mode, write requests are rejected outright. Note that approval **only escalates this one write—it does not expand the read scope**—the only way to read files outside the workspace is path authorization (see section 2).

### Terminal sessions: identity pinned, switching closes them

The read/write identity of persistent terminal sessions (terminal family of tools) is **pinned** at startup according to the current permission tier, execution environment, and sandbox policy: under restricted tiers (readonly/approval/auto_approval) the terminal runs with read-only identity and writes inside the terminal are denied directly by the system (EPERM); only under `unrestricted` is the identity writable. When you **switch the execution environment (sandbox ⇄ direct), switch the permission tier between restricted and unrestricted, or switch workspace or container**, existing terminal sessions are **closed immediately**—they never keep running with the old identity, and subsequent operations run in a freshly spawned session under the new policy. This also means: don't switch these toggles while running long tasks, because the task terminates together with the session.

### Sub agents and background commands

Sub agent terminal processes also go through the execution environment policy: under sandbox they are launched via the host sandbox; under direct they launch directly on the host; in docker mode they execute inside the container. Background commands (`run_in_background`) go through the same read-only/writable sandbox determination as foreground commands—**going to the background does not bypass permissions**.

## 2. Day-to-Day Management of Path Authorization

Entry point: input bar `+` menu → "Path authorization".

- **Readable and writable paths**: the AI's full working scope, typically your project directory;
- **Read-only paths**: allow the AI to consult but not modify, e.g., reference docs, online config samples, and other projects' source code.

Suggested practices:

1. Keep authorization minimal—only add the directories the current task needs;
2. Never add sensitive directories (`~/.ssh`, key stores, system directories) under any category;
3. Adjust promptly when the nature of a task changes. Authorization takes effect immediately (except for new terminal sessions, see above).

## 3. Network Permission

An independent group in the input bar permission menu:

- **Restricted** (default): loopback only; the AI cannot reach the external network—suited for purely local tasks and prevents data exfiltration;
- **Fully open**: allows outbound/inbound connections—enable it when the AI needs to search the web, call external APIs, or install dependencies.

Network permission is independent of the file sandbox and can also be adjusted in plan mode.

## 4. Approval Panel

Entry point: `+` menu → "Approval panel". Here you can see the approval history: which commands/writes were submitted for approval, who approved them (human or the auto-approval agent), and the outcome. In `auto_approval` mode, if you don't want the panel to pop up automatically, there is a toggle in Personal Space (not auto-opened by default).

## 5. Forbidden Command List

The deployment-level config `forbidden_commands.json` (placed in `<data root>/config/`) can define **command patterns that are absolutely forbidden to execute**. Any match is rejected regardless of permission mode. This is the last line of defense—suitable for locking down commands like `rm -rf /` and `shutdown` on server deployments.

## 6. A Word of Caution About direct Mode

`direct` = commands execute directly on the host, **with no sandbox at all**. It is hard-mutually-exclusive with the restricted tiers (readonly/approval/auto_approval)—only `unrestricted` can select direct, and switching from direct into a restricted tier automatically pushes you back to sandbox. There is exactly one legitimate use case: a command genuinely cannot run inside the sandbox (requires system-level permissions) and there is no alternative. In that case:

1. First switch the permission tier to `unrestricted`, then temporarily switch to direct;
2. Switch back to sandbox (and the original permission tier) as soon as the command is done;
3. Note that after direct is switched on, it **persists and does not revert automatically**—forgetting to switch back means running unprotected long-term.

## 7. Current Security State of docker Mode

In docker mode, the isolation boundary between users is the container itself: each user's terminal runs in an independent container, invisible to each other. The permission constraints **inside** the container are also truly enforced:

- Under restricted tiers (readonly/approval/auto_approval), run_command, background commands, and persistent terminals all execute as a **non-privileged user (uid 10001)** inside the container—the workspace is owned by root, and writes are denied directly by kernel file permissions, without relying on recognizing command text; after approval, only that one command is retried as root;
- Prerequisites: the workspace is owned by root, there are no globally writable files, and the container does not mount docker.sock (all satisfied by following the official deployment docs);
- This enforcement holds only on **Linux hosts**—Docker Desktop on a local macOS machine does not enforce uid file permissions, so don't treat container-internal permissions as a security boundary during local development;
- Multi-user deployments should combine container resource limits, image minimization, and other standard container security practices.

## 8. Security Posture by Platform

Reiterating the conclusion from the "Core Concepts" chapter, because it directly affects how much you should trust the sandbox:

- **Windows (WSL2)**: tested; full data isolation is achievable, but WSL2 must be installed first;
- **macOS (sandbox-exec)**: tested; whitelist read model—both writes and reads can be restricted: processes can by default only read system directories, the workspace, and authorized paths; the trade-off is that top-level file names in the ancestor directories of authorized paths can be listed (file contents remain unreadable);
- **Linux (bwrap+seccomp)**: **untested, unadapted, and currently unavailable**—for multi-user deployments on Linux servers, use Docker mode (container isolation is tested and effective); do not rely on the host sandbox.

On any platform, the primary value of the sandbox is **preventing accidental operations**; for genuinely sensitive data, layer path authorization minimization, restricted network, and readonly permissions together for comprehensive protection.