Core Concepts

Astrion is built on four sets of mutually orthogonal concepts. Understanding them is the key to understanding the entire system: any combination of them determines what a task "can do, where it runs, and to what extent".

Concept group	Values	Determines	Where to switch
Deployment mode	host / docker(web)	Where data is stored, and whether commands run on the host or in a container	Environment variable (set at deploy time)
Permission mode	readonly / approval / auto_approval / unrestricted	Whether AI tool calls require approval	Permission menu in the input bar (per conversation)
Execution environment	sandbox / direct	Whether commands go through the OS sandbox	Permission menu in the input bar (per conversation, host mode only)
Work mode	plan / ask / execute	The pace of AI's interaction with you: plan first or act directly	Work mode switcher in the input bar (per conversation)

1. Deployment Mode: Host vs Docker (Web)

Deployment mode is determined before startup by the environment variable TERMINAL_SANDBOX_MODE and cannot be switched at runtime.

Host mode: designed for local personal use. Commands run through the host OS sandbox, and the AI can directly operate on the local directories you have authorized (such as a real project repository). The file manager and local Node/Python toolchains are directly available.
Docker mode (web mode): designed for multi-user server deployment. Each user's terminal commands run in an independent Docker container, and files and processes are naturally isolated between users. You need to build the sandbox image first (see "Quick Start").

The two modes keep completely separate data directories (~/.astrion/astrion/host/ and web/), but host mode merges and reads the user and workspace lists from web mode — so historical data from both modes on the same machine is visible.

Note: Docker mode also enforces read-only — under restricted permission levels (readonly/approval/auto_approval), commands run inside the container as a non-privileged user (uid 10001), and writes are directly rejected by kernel file permissions. The two-stage "read-only → approval → single writable retry" flow is identical to host mode (see "Execution & Security" for details).

2. Permission Mode: What the AI Can Do

Permission mode is a product-level switch that determines whether tool calls are intercepted and whether approval is required. It is switched per conversation and can be changed at any time.

Read-only

run_command is allowed, but runs in a read-only sandbox; once the command attempts a write, the operating system directly returns a permission denial (e.g., Operation not permitted).
Write tools such as write_file / edit_file are directly rejected.
Use cases: when you want the AI to only do code review, read-only analysis, or answer questions.

Approval (default)

run_command follows a two-stage flow: first it runs in a read-only sandbox → if a permission denial occurs, an approval request is raised to the frontend → after you approve, only that command is retried once in a writable sandbox.
The tool returns the final result after the retry; the AI never sees the intermediate denial process.
If approval is denied or times out: the command is not executed and nothing is written.

Auto-approval

The same "read-only first" flow as approval, except the approver is an auto-approval agent (an independent AI whose model and parameters can be configured in Personal Space).
write_file / edit_file: targets inside the workspace execute directly; targets outside the workspace go through auto-approval.
When auto-approval is denied, the AI receives a "denied + reason" and continues trying other paths without interrupting the whole round of tasks.
You can take over manually at any time: approve / deny / switch to Unrestricted.

Unrestricted

The permission layer performs no interception; tools execute directly.
At this point the security boundary is entirely determined by the execution environment (see the next section): under sandbox the OS sandbox still provides a safety net, while under direct it is equivalent to running bare.

3. Execution Environment: Sandbox vs Direct

The execution environment is a system-level switch (switchable in host mode only) that determines whether commands ultimately pass through the OS sandbox:

sandbox (default): commands run inside the OS sandbox, and the read/write boundary is limited by "path authorization". When the sandbox is unavailable, critical execution paths are refused to run rather than silently falling back to the bare host.
direct (high risk): commands run directly on the host with no sandbox restrictions. It is selectable only under the unrestricted permission — restricted levels (readonly/approval/auto_approval) and direct are strictly mutually exclusive: switching to direct under a restricted level is rejected, and switching from direct into a restricted level is automatically pushed back to sandbox. It is only recommended to enable it temporarily when system-level privileges are clearly needed, and to switch back immediately after use. Once switched, it stays in effect — there is no automatic fallback mechanism.

Sandbox Implementation and Security Level by Platform (Please Read)

Platform	Implementation	Security level
Windows	WSL2	Full data isolation is achievable — commands run in an independent WSL2 filesystem. Prerequisite: install WSL2 yourself first; the sandbox is unavailable without it
macOS	sandbox-exec	Whitelist-based read model; both reads and writes can be restricted — by default a process can only read system directories, the workspace, and authorized paths; out-of-bounds reads are directly denied. Inherent cost: file names at the top level of an authorized path's ancestor directories can be listed (file contents remain unreadable)
Linux	bubblewrap (bwrap) + seccomp	Writes can be restricted (read-only level is globally read-only), but reads are still globally readable and not yet aligned with a whitelist; it has not been tested in practice, so relying on its isolation in production is not recommended

This is the official, candid statement of current security capabilities: as a way to prevent accidental mistakes, the sandbox is reliable on all three platforms; as a way to prevent malicious data theft, macOS (whitelist) and Windows (WSL2) can be trusted, while Linux cannot — for now.

Path Authorization

In host mode, the sandbox's file access boundary is determined by path authorization, which has two categories:

Read-write paths: the AI can read and modify them;
Read-only paths: the AI can view but not modify them.

Relationship: readable set = read-write + read-only; writable set = read-write. Maintained in the input bar + menu → "Path Authorization". It is recommended to keep authorization minimal: workspace + temporary directory.

The read/write identity of a terminal session (terminal family of tools) is pinned at startup according to the permission level, execution environment, and sandbox policy at that time: under a restricted level the terminal runs as read-only, and only under unrestricted does it run as writable. Switching the execution environment (sandbox ⇄ direct), toggling the permission level between a restricted level and Unrestricted, or switching the workspace or container closes existing terminal sessions immediately, after which subsequent operations run in freshly spawned sessions under the new policy.

Network Permissions

A separate set of switches independent of the file sandbox (also adjustable in Plan mode):

Restricted (default): only local loopback access is allowed; external networks are unreachable;
Fully open: all outbound/inbound connections are allowed.

4. Work Mode: The Pace of AI's Interaction with You

Work mode controls when the AI acts and when it asks you first, and is fully orthogonal to permissions. It can only be switched while idle (switching during a running task returns a 409 notice).

Plan: the AI only drafts a plan and discusses it with you, without actually changing anything. In this mode, permissions are locked to read-only and the execution environment is locked to sandbox (enforced on both the UI-disabled side and the backend, except for network permissions). The only exception is writing plan documents under .astrion/plan/*.md. Once the plan is written, the AI calls submit_plan to ask for your approval; approving automatically switches to Execute and restores your previous permission settings.
Ask: discuss first, then start working. The AI writes its approach and questions in replies and confirms them back and forth with you, acting only after key details are settled. At the execution level there is no difference from Execute — only the pace of interaction differs.
Execute: the AI works out the plan and fills in details on its own, and starts working directly, asking questions only when it hits a hard blocker (missing information, account credentials required, etc.).

Common Combinations

Scenario	Recommended combination
Have the AI modify an important project you are maintaining	plan + approval + sandbox
Everyday casual use that prioritizes efficiency	execute + auto_approval + sandbox
Pure Q&A / code review; files must never be touched	any mode + readonly (execution environment automatically locks to sandbox)
Multi-user server deployment	Docker mode (the execution environment concept does not apply)

5. Quick Reference: Interaction Rules Between the Four Concept Groups

Plan mode → permissions are forced to readonly, execution environment is forced to sandbox (network permissions remain adjustable);
Restricted permission levels (readonly/approval/auto_approval) → execution environment is automatically locked to sandbox; direct is only available under unrestricted;
Approving a plan → automatically switches to execute and restores the permission and execution environment from before entering plan;
In Docker mode there is no sandbox/direct distinction — the container is the boundary;
Permission mode, execution environment, and work mode are all per-conversation state: a new conversation inherits the current input bar values, and the "default permission mode / default work mode" in Personal Space only affects the first construction.

11 KiB Raw Blame History