Workspace — Alius Docs

What is a Workspace?

A Workspace is Alius’s core organizational unit. A workspace maps to a project directory. All AI Agent activity — Sessions, plans, memory, Traces — takes place within this workspace scope.

Alius’s workspace is not a simple chat interface, but a Plan-driven Agent runtime workspace. It is designed around goal understanding, plan generation, controlled execution, and result review.

your-project/
├── .alius/
│   ├── config/         # Project configuration
│   ├── memory/         # Project memory storage
│   ├── workspace/      # Workspace documents
│   └── runtime/        # Runtime state (e.g., initialization progress)
├── src/
└── ...

Why Workspace-based?

Traditional AI tools organize around conversations. Alius organizes around your actual project:

Traditional AI CLI	Alius
Organized around conversations	Organized around real projects
Returns text that needs interpretation	Produces Plans, Runs, Traces, and recoverable context
Configuration scattered across machines	Everything stored under `.alius/`
Hardcoded model assumptions	Lets you configure Provider, Model, API Key, and Soul
Single mode	Plan-driven + Bypass dual mode
No security boundary	Shell Gate risk analysis and approval control

Initialize a Workspace

alius init

This creates the .alius/ directory structure and launches the initialization wizard. The wizard is a resumable state machine that guides you through:

Language selection — Choose the workspace interface language
Model pool configuration — Import models from supported providers
Model assignment — Assign models to the Plan/Execute/Review roles
Soul selection — Choose the Agent role identity

If .alius/ already exists, /init will ask whether to reinitialize or exit. Reinitializing clears the model pool, role selection, and language override. Initialization progress is saved in .alius/runtime/init-state.toml and can be resumed after interruption.

Workspace Scope

All AI operations are scoped to the workspace:

File access is limited to the workspace directory (resolve_within_workspace blocks absolute paths, ../ traversal, and symlink escapes)
Memory is stored per project
Sessions belong to the workspace
Shell commands go through Shell Gate risk analysis and approval

Operations beyond the workspace require explicit authorization or are directly denied.

TUI Workspace Layout

The interactive workspace contains the following main areas:

Area	Purpose
Top bar	Version, Soul, mode, and network status
Session area	Workflow conversation blocks (Request, Understanding, Plan Proposal, Execution, Prompt, Output, Error)
Plan panel	Plan nodes, status, acceptance criteria, and evidence (appears only after Plan mode approval)
Interaction area	Text input, option selection, and approval controls
Status bar	Current workspace, Git status, and runtime status

Welcome Screen

Each time the workspace starts, the session area displays a welcome block containing the version number, current Soul, model assignment, and Enter prompt. The welcome block has four layout variants (Wide / Medium / Compact / Tiny) based on terminal size, ensuring readability across different terminal dimensions.

Conversation Blocks

The workspace uses a workflow language instead of the traditional User/Assistant format:

Block Type	Description
Request	User request
Understanding	Model’s understanding of the task
Plan Proposal	Plan proposal
Execution	Execution process
Prompt	Interactive prompt
Status	Status update
Output	Output result
Error	Error message

Long conversation blocks (over 3 lines) auto-collapse. Click to expand, or use Ctrl+O to toggle globally.

Configuration Structure

.alius/config/
├── config.toml        # Main configuration (runtime metadata, default model/provider, UI, Session, logging)
├── providers.toml     # Provider definitions, compatible routing layer, local model library, Base URL and API Key
├── model.toml         # Plan/Execute/Review model assignment
├── soul.toml          # Agent identity (Agent Card compatible configuration)
├── tools.toml         # Built-in/MCP/plugin/workflow tools, timeouts, confirmation, and registration settings
├── permissions.toml   # File system, Shell, network, memory, project document, and remote A2A permissions
├── protocol.toml      # Protocol interface enablement and event/command settings
└── mcp.json           # MCP server declarations

Project Discovery

Alius discovers the project root by searching upward from the current directory for a .alius/ directory. You can start alius from any subdirectory within the project, and it will automatically find the project root.