242 lines
12 KiB
Markdown
242 lines
12 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```json
|
|
{
|
|
"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**:
|
|
|
|
```json
|
|
{
|
|
"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**:
|
|
|
|
```json
|
|
{
|
|
"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.
|