JOJO/astrion-website
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
56697a04ed
astrion-website/content/en/01-quick-start.md

12 KiB
Raw Blame History

Quick Start

This chapter walks you through running Astrion from scratch: cloning the code, completing the initial configuration, starting the service, and choosing the right runtime shape for your use case.

1. System Requirements

Dependency Requirement Notes
Python 3.9+ (3.11 recommended) Backend runtime
Node.js 18+ Building the frontend, using the CLI
Docker Optional Required only for web/docker mode; not needed for host mode
WSL2 Windows only Prerequisite for using the host sandbox on Windows

Astrion runs on macOS, Linux, and Windows (WSL2). For the differences in sandbox capabilities across the three platforms, see the "Core Concepts" chapter.

2. Installation

# 1. Clone the repository
git clone https://github.com/JOJO6618/astrion.git
cd astrion

# 2. Initialize: create a venv, install dependencies, and run the interactive setup wizard
#    The wizard asks, in order: work mode → listen address/port → admin account → model API → generate secret keys
./setup.sh

# 3. Build the frontend
npm install && npm run build

# 4. (web/docker mode only) Build the sandbox image; see "Choosing a work mode" below
docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest .

# 5. Start
./start.sh
# Or start manually:
python -m server.app --port 8091 --thinking-mode

After startup, visit http://localhost:8091 and log in with the admin account you set up in the wizard.

The setup.sh wizard writes the configuration to .env at the repository root. This is a development fallback; for production deployments we recommend using the settings.json under the data root or system environment variables instead. See "Configuration priority" below.

3. Port and Listen Address

  • Default port: 8091 (WEB_SERVER_PORT).
  • Listen address (WEB_SERVER_HOST):
    • Single-machine personal use: 127.0.0.1 is recommended — listens only on the local loopback, unreachable from the LAN;
    • Multi-user / server deployment: use 0.0.0.0.
  • The --port CLI argument can temporarily override the configuration.
  • Debug mode WEB_SERVER_DEBUG=1 (also enables the Flask reloader); keep it at 0 in production.

4. Data Paths: Where Data Lives and How to Move It

Astrion's runtime data (conversation records, users, logs, deployment-level config) is by default stored entirely under your home directory and never pollutes the source tree:

~/.astrion/astrion/           ← data root (data_root)
├── settings.json             ← single configuration file (highest priority)
├── config/                   ← deployment-level config (model libraries, etc., shared by host/web)
├── host/                     ← host mode data
│   ├── data/  users/  logs/  api/
└── web/                      ← web/docker mode data (same structure above)

Data is routed automatically by work mode: when TERMINAL_SANDBOX_MODE=host, data goes into host/; otherwise it goes into web/.

Path-Related Environment Variables (priority from high to low)

Environment variable Purpose
DATA_DIR / LOGS_DIR / USER_SPACE_DIR / API_USER_SPACE_DIR Override a single directory individually (highest priority)
ASTRION_DATA_ROOT Move the entire data root (default ~/.astrion/astrion)
DEPLOY_CONFIG_DIR Move just the deployment-level config directory (default <data root>/config/)

Individual directory variables accept relative paths (resolved relative to the repository root), absolute paths, and ~.

Configuration priority

Effective order for same-name configuration: <data root>/settings.json > system environment variables > .env at the repository root > code defaults.

.env does not override existing system environment variables when loaded; settings.json is the recommended way to configure production, for example:

{
  "server": { "port": 8091, "host": "127.0.0.1" }
}

5. Configuring the Main Agent Model

The main agent's models are registered centrally in custom_models.json.

Placement (looked up by fallback chain; first hit wins):

  1. <data root>/config/custom_models.json (recommended for production)
  2. config/custom_models.json inside the repository
  3. config/custom_models.json.example inside the repository (seed example)

Full field reference:

{
  "models": [
    {
      "model_name": "Kimi-K3",
      "description": "Model description shown to users",
      "visible": true,
      "url": "${API_BASE_KIMI}",
      "apikey": "${API_KEY_KIMI}",
      "multimodal": "image,video",
      "reasoning_capability": "fast,thinking",
      "reasoning_effort": true,
      "context_window": 1048576,
      "max_output_tokens": 64000,
      "thinkmode_status": {
        "type": "param_toggle",
        "model_id": "k3",
        "fast_extra_parameter":     { "thinking": { "type": "disabled" } },
        "thinking_extra_parameter": { "thinking": { "effort": "max" } }
      },
      "extra_parameter": {},
      "model_description": "Model self-description injected into the system prompt"
    }
  ]
}
Field Required Description
model_name ✅ Model entry name; shown in the UI and used as the key that other config references
url ✅ Base API address. Supports ${environment variable} references; don't write secret keys in plain text
apikey ✅ API key, also supports ${...}
description Description text shown in the list
visible Whether it is visible in the model selection menu
multimodal image,video, etc.; determines whether the input bar allows sending images/videos
reasoning_capability fast,thinking; determines the available thinking mode options
reasoning_effort Whether the "reasoning effort" slider is supported
context_window Context window size (tokens); the baseline for compression thresholds and usage statistics
max_output_tokens Maximum output tokens per response
thinkmode_status param_toggle type: model_id is the real model ID; fast/thinking_extra_parameter are the extra request parameters attached in each of the two modes respectively
extra_parameter Extra parameters attached to every request
model_description Self-description injected into the system prompt

Minimum config needs only 4 fields: model_name / url / apikey / thinkmode_status.model_id; all other fields have defaults.

Note: the model entry created by the setup.sh wizard in step 5 is exactly the minimum config — multimodal is none (cannot send images/videos), context_window is fixed at 128000, and max_output_tokens is 32768. If your model supports multimodality or a larger context, edit <data root>/config/custom_models.json manually after running the wizard to fill in the fields.

Default model: when AGENT_DEFAULT_MODEL is not set, the first visible model in the list is used; you can also set a per-user default model in the "Models & Thinking" page in Personal Space.

Note: the legacy AGENT_API_* / AGENT_THINKING_* / AGENT_TITLE_* environment variables have been removed from the code; configuring them no longer has any effect.

6. Configuring Sub Agent Models

Sub agents (including the three review agents) use a separate model library: sub_agent_models.json.

Placement: it is read only from the deployment config directory — <data root>/config/sub_agent_models.json (can be overridden individually with SUB_AGENT_MODELS_CONFIG_FILE). Without this file, sub agents will fail to start and report "no usable sub agent model configuration found".

Structure:

{
  "default_model": "deepseek-v4-flash",
  "models": [
    {
      "name": "deepseek-v4-flash",
      "url": "${SUB_AGENT_API_BASE}",
      "apikey": "${SUB_AGENT_API_KEY}",
      "model_id": "deepseek-v4-flash",
      "modes": "fast,thinking",
      "multimodal": "image",
      "max_output": 32000,
      "max_context": 128000,
      "extra_parameter": {},
      "fast_extra_parameter": {},
      "thinking_extra_parameter": {}
    }
  ]
}

Key points:

  • default_model: the default entry name; used when model is left empty in sub agent / review agent config. If the specified name does not exist, it falls back to the first available entry in the list.
  • Field names are loosely compatible: name/model_name/model, url/base_url, and apikey/api_key all work; modes set to fast,thinking means thinking mode is supported, while just fast means fast-only mode.
  • The same thinkmode_status structure as the main model library is also supported; you can copy an entry from custom_models.json, rename it, and use it directly.
  • url / apikey also support ${environment variable} references.

Sub agent environment variables:

Variable Default Description
SUB_AGENT_MAX_ACTIVE 5 Maximum number of simultaneously running sub agents
SUB_AGENT_DEFAULT_TIMEOUT 180 (seconds) Default timeout
SUB_AGENT_TASKS_BASE_DIR <data root>/<mode>/data/sub_agent_tasks Task directory
SUB_AGENT_PROJECT_RESULTS_DIR <workspace>/sub_agent_results Delivery directory (intentionally placed inside the workspace)

7. Choosing a Work Mode: host or docker (web)

Determined by TERMINAL_SANDBOX_MODE; the two modes target completely different scenarios:

host mode web/docker mode
Positioning Local personal use Multi-user server deployment
Command execution Host OS sandbox (macOS sandbox-exec / Linux bwrap / Windows WSL2) Per-user isolated Docker container, executed as a non-privileged uid under restricted permissions
Data directory ~/.astrion/astrion/host/ ~/.astrion/astrion/web/
Prerequisites No image needed; Windows requires WSL2 first Must build the image first: docker build -f docker/terminal.Dockerfile -t my-agent-shell:latest . (the build context must be the repository root)
Image name — Specified by TERMINAL_SANDBOX_IMAGE; my-agent-shell:latest is recommended

Recommendations:

  • Using it alone on your own computer → host. The file manager and local toolchain work directly; the best experience.
  • Deploying to a server for multiple users → docker. Containers naturally isolate files and processes between users.
  • host mode can also read web mode data (user list, merged workspace display); the reverse is not possible.

The sandbox image is based on python:3.11-slim and ships with a common toolchain: LibreOffice / Pandoc / FFmpeg / Tesseract OCR (with Chinese) / Chromium / Node 20 / docx / pptxgenjs, etc. The program does not build the image automatically; you must build it manually once before starting web mode.

8. First-Start Checklist

  1. Open http://localhost:8091 in a browser and log in with the admin account;
  2. Go to Personal Space and confirm the "Models & Thinking" page shows the models you configured;
  3. Send a message and confirm the main agent replies normally;
  4. Have the main agent create a sub agent (or trigger one by saying "help me look up xxx"), and confirm sub_agent_models.json is configured correctly;
  5. For web mode, confirm the image has been built and the terminal container starts properly.

At this point, your Astrion is up and running. Next, we recommend reading "Core Concepts" to understand four sets of concepts — deployment modes, permission modes, execution environments, and work modes — which define the boundaries of Astrion's behavior.