# agentlas ``` █████╗ ██████╗ ███████╗███╗ ██╗████████╗██╗ █████╗ ███████╗ ██╔══██╗██╔════╝ ██╔════╝████╗ ██║╚══██╔══╝██║ ██╔══██╗██╔════╝ ███████║██║ ███╗█████╗ ██╔██╗ ██║ ██║ ██║ ███████║███████╗ ██╔══██║██║ ██║██╔══╝ ██║╚██╗██║ ██║ ██║ ██╔══██║╚════██║ ██║ ██║╚██████╔╝███████╗██║ ╚████║ ██║ ███████╗██║ ██║███████║ ╚═╝ ╚═╝ ╚═════╝ ╚══════╝╚═╝ ╚═══╝ ╚═╝ ╚══════╝╚═╝ ╚═╝╚══════╝ ``` **Agentlas Terminal CLI** — Independent AI agent runtime installed via `npm install -g agentlas` and launched with `agentlas`. Run exact installed agents, teams, and parallel sessions directly from your shell without keeping Desktop open. When Desktop is installed, Terminal reads the same local project, agent, and runtime state. Bring your own model — use Antigravity (`agy`), Claude Code, Codex, legacy Gemini CLI, or BYOK API keys. Use this existing independent Terminal as the command-line runtime: inspect owner-private packages with `agentlas cloud list`, restore one with `agentlas cloud restore `, or install an eligible public package with `agentlas install `. > **We are Agent Trust. Your agent is not a program. It is an asset. — Agentlas —** Agent Trust is our product principle: agent packages are treated as portable, owner-scoped, inspectable, and restorable assets. (It does not imply regulated financial or fiduciary services.) Agent Cloud stores package assets in your private cloud account, while Agentlas Terminal verifies and executes local runtime copies on your host machine. Current release: 1.0.67. It hardens local Cloud and credential storage against path races, keeps ACP notifications protocol-correct, aligns CLI machine output and typed errors, binds Workforce selections to exact ontology versions, rejects duplicate Experience requirements, and makes MCP consent and Hub installs race-safe. --- ## Requirements | Category | Requirement | | --- | --- | | **Node.js** | **Node 22+ recommended.** `package.json` specifies `engines: ">=20"`, but if native optional dependency `better-sqlite3` build fails, the launcher falls back strictly to `node:sqlite` in Node 22+. Node 20 works when `better-sqlite3` native build succeeds. | | **Agent CLI** | Requires at least one supported runtime CLI: `agy` (Antigravity, preferred), `claude`, `codex`, or legacy `gemini` in your `PATH`. Halts honestly with `no_runtime` if none are found (no fake model responses). | | **OS** | macOS is verified by the current local release gate. Linux is covered by the public adapter/CI contract. A Windows launcher is provided, but this release does not claim independent end-to-end Windows verification. | *Note: active runtimes include `claude-code`, `codex`, `agy` (Antigravity), legacy `gemini`, and the shared ACP-backed `kimi`, `grok`, and `cursor-agent` adapters. `doctor` reports the exact locally executable set.* ## Installation ```sh npm install -g agentlas # Or from local source: npm install -g . # Or via shell installer: sh install.sh # Symlinks to ~/.local/bin/agentlas (no sudo needed) # Or with custom prefix: sh install.sh --prefix /usr/local/bin ``` Windows (launcher available; end-to-end release not independently verified): `powershell -ExecutionPolicy Bypass -File install.ps1` ## Quick Start ```sh agentlas ``` **1. Interactive Onboarding Wizard** — On first TTY execution, a 3-step setup guides you through language selection, default runtime preference (`auto` or installed CLI), and default permission level (`read`/`write`/`full`). Settings are saved in `cli-prefs.json` and re-configurable via `agentlas setup`. If no local database exists, it bootstraps SQLite with Desktop-compatible schemas and seeds built-in agents (Orchestrator, PM Soul, Memory Curator). **2. Single Task Execution** ```sh agentlas "Identify why repository tests are failing" # Uses the connected project's first agent as controller agentlas run -p "Summarize the last 3 CHANGELOG entries" # Prints the project controller's final answer to stdout git log --oneline -20 | agentlas run # Reads stdin; still requires a connected project agentlas run "Advanced direct request" # Explicit one-turn exact-agent override agentlas firm "Request" # Delegates to an exact firm CEO ``` Ordinary one-shot work is project-first: run it inside a folder connected to a Desktop Work project. The first agent in that project's ordered pool owns the task; remaining members are eligible task-scoped sub-agents. Missing projects, empty teams, and unavailable controllers stop without substituting another agent. The separate `agentlas route` preview is model-judged and stays unresolved when no exact installed agent can be justified. ## Command Reference Run `agentlas help` for the authoritative command list. Below is the organized command structure: ### PROJECT WORK ```sh agentlas # Open the connected project's controller session agentlas run [agent] [prompt] # Project-first run; optional agent is one explicit turn agentlas one [""] [--list|--new] # Personal agent One — continues the same shared-DB One conversation agentlas firm [task] # Delegate task to firm CEO agentlas cd # Print folder path of an agent (cd "$(agentlas cd x)") ``` ### AGENTS & HUB ```sh agentlas search "" # Search Hub agents (no login required) agentlas install # Install Hub agent locally (gated by security trust checks) agentlas plugin add # Add Hub plugin (MCP server) agentlas plugin list # List active plugins agentlas build "" # Build, repair, and package agents or multi-agent teams agentlas upload # Upload package to private Agent Cloud (default) agentlas upload --visibility marketplace # Explicitly publish to public Agentlas Hub agentlas connect # Connect external platforms (e.g. Telegram) agentlas import # Import local agent or firm directory agentlas native prepare # Generate native CLI context files agentlas agents # List installed agents/firms and active runtimes (alias: list) agentlas uninstall [--yes] # Remove an installed agent (fails if chat history exists unless --yes) agentlas experience # Manage agent experience (list|inspect|validate|save|publish|status|export|unpublish|withdraw) agentlas variant resolve --base-release # Preview local variant compatibility agentlas roles [set ] # Inspect or set the orchestrator/worker model roles ``` ### EXECUTE ```sh agentlas storm "" # Goal + UltraCode harness: plan -> assign -> execute -> verify [--research] agentlas swarm "" # Emergent multi-agent swarm [--parallel N] agentlas workforce "" # Route through Agent Workforce Ontology (public Hub menu) agentlas network "" # Alias for workforce agentlas taskforce "" # Alias for workforce agentlas hep-network "" # Staff across Local + owner Cloud + public Hub (local Core federation) agentlas hep-local "" # Same staffing, registered Local agents only agentlas hep-cloud "" # Same staffing, owner Agent Cloud only agentlas hep-hub "" # Same staffing, public Hub only agentlas call "a,b" "" # Call explicitly named Hub or Cloud agents agentlas browser [...] # Real browser hardpoint launcher (opens an owned tab) agentlas route "" [--json] # Preview routing decisions without execution agentlas research # Research loadout (status|gather|search|read|plan) ``` ### KNOWLEDGE ```sh agentlas memory import --agent [--apply] agentlas evolve [list|apply |revert ] agentlas ontology # Manage project ontology (status|list|add) # Derived career-graph indexing is owned by the installed Hephaestus runtime; # use `agentlas ontology` for source registration. # Run-journal diagnosis is an expert Hephaestus path: # agentlas hep stormbreaker journal --run-id --journal agentlas project [status|init] # Explicit entry point to initialize `.agentlas/` context agentlas context # Context slice operations (refresh|locate|refs|slice|impact|verify) agentlas graph [list|show|run ] # Saved automation graphs (built in Desktop's Graph editor) ``` Only in projects explicitly initialized with `agentlas project init` do single runs, team executions, Stormbreaker, and Workforce receive local Context Slices. Read, write, or full permissions do not create or alter `.agentlas/` or `.gitignore` files. Code maps, source paths, and file contents are never transmitted during Hub/Cloud search. ### ACCOUNT & OPS ```sh agentlas login # Agentlas Cloud authentication (loopback browser flow) agentlas logout # Clear the saved CLI session agentlas whoami # Show the signed-in account agentlas billing # Check account credit balance agentlas cloud # Manage private Agent Cloud packages (save|publish|package|list|restore|delete|search|install|security scan|runtime bundle|field-test) agentlas automation # Scheduled automations (list|add|on|off|remove|run |runs|daemon) agentlas creds save --provider --key --value agentlas creds file --source [--env ] # Imports credentials (values never logged) agentlas env # List shared environment variable keys (values hidden) agentlas usage # Local usage statistics agentlas telegram # Telegram binding status (read-only) agentlas mcp # List configured MCP servers agentlas mcp probe # Check initialize -> tools/list handshake agentlas multimodal # Configure provider settings for image/video/audio agentlas doctor # Runtime, database, and session diagnostics agentlas setup # Re-run first-time onboarding setup wizard (TTY required) agentlas update # Check for latest package updates on npm agentlas oberon # AI film rendering pipeline: scaffold|render|list|open (= agentlas film) agentlas hep # Native Hephaestus passthrough agentlas netadmin # Local network administration (init|status|reindex|bench|add-source) agentlas acp [--info] # Run as an ACP agent for editors (Zed, JetBrains, …) agentlas document pdf # Export a document to PDF agentlas version | help ``` Common flags across subcommands: `-p|--print`, `--runtime claude-code|codex|agy|gemini`, `--permission read|write|full`. ### Typo Guard & Desktop Surface Redirection If a single non-flag word is entered that does not match a valid command or installed agent slug, Agentlas halts with exit code 1 instead of sending the mistyped command to an LLM: ``` $ agentlas lst 'lst' is not an agentlas command. Did you mean: list Command list: agentlas help · To run this exact prompt: agentlas run -p "lst" ``` Desktop-only surface names (`site`, `sites`, `trex`, `slides`, `prompts`, `dashboard`, `marketplace`, `library`, `settings`, `apps`, `quests`, `bookmarks`) also halt with typo guard guidance directing you to equivalent terminal commands. To run a single word as a prompt, wrap it in quotes or pass `run -p`. (`agentlas one` is a real terminal command — the shared-DB personal agent, not a Desktop-only surface — see PROJECT WORK below.) ### Permission Levels | Agentlas Level | Claude Code | Codex | Gemini CLI | | --- | --- | --- | --- | | `read` | `plan` | `read-only` sandbox | `plan` | | `write` | `acceptEdits` | `workspace-write` sandbox | `auto_edit` | | `full` | bypass permission prompts | approval + sandbox bypass | `yolo` | *Note: Saved `full` permission is session-bound and automatically fails closed to `write` on subsequent executions. REPL shell execution (`!`) runs strictly under `full` permission, enforced with 8MB output capping, secret masking, and process-group termination.* ## Project Work Execution Tree Executing `agentlas` with no arguments resolves the current folder to an Agentlas project and starts its first ordered agent as the task controller. The controller may create task-scoped worker runs; users can inspect the real execution tree, but cannot replace the controller or address workers around it. ### REPL Slash Commands | Command | Action | | --- | --- | | `/help` | Display available commands and keybindings | | `/sessions` · `/tree` | View session table or parent-child process tree | | `/s ` · `/switch ` | Switch active session (replays tail logs & subscribes to live stream) | | `/kill ` | Interrupt active turn in session `n` | | `/rm ` | Remove session `n` | | `/agents` · `/list` | List installed agents | | `/mcp` | List active MCP servers | | `/doctor` | Run runtime & database diagnostics | | `/runtime ` | Set runtime for new sessions (`claude-code` \| `codex` \| `agy` (Antigravity) \| legacy `gemini`) | | `/permission ` | Set permission level for new sessions (`read` \| `write` \| `full`) | | `/quit` · `/exit` | Exit REPL | Unrecognized slash commands halt with `unknown: /xxx (see /help)`. ### Controls & Input Shortcuts | Input | Behavior | | --- | --- | | Typing + `Enter` during execution | Queues message into session's **steering queue** for next turn (does not abort current turn) | | `Ctrl+C` (during execution) | Interrupts current turn | | `Ctrl+C` (when idle) | 1st press shows warning; **2nd consecutive press exits** | | `Tab` | Autocompletes slash commands, agent/firm slugs, **live session keys (s1, s2...)**, and `/runtime` / `/permission` values | | `@path` + `Tab` | Autocompletes local file paths | | `Up` / `Down` | Input history navigation | | `!` | Execute shell command (requires **`full` permission**) | Parallel execution limit defaults to 4 concurrent sessions. Exceeding the limit halts with explicit refusal; increase limit via `AGENTLAS_MAX_PARALLEL` (up to 16). ## Operating Architecture ### Engine Boundary — No Duplicated Core OS Logic Agentlas Terminal does not re-implement Agentlas OS. It resolves and executes the installed **Agentlas OS (Hephaestus/Core)** runtime on your system. Runtime Search Order (`engine/agentlas-core-harness.cjs`, `engine/hephaestus/runtime.cjs`): 1. `HEPHAESTUS_BIN` / `HEPHAESTUS_RUNTIME_ROOT` 2. `~/.agentlas/runtime/current` 3. Packaged Core (`/Hephaestus`, macOS: `/Applications/Agentlas.app/Contents/Resources/Hephaestus`) Commands including `storm`, `swarm`, `workforce`/`network`, `route`, `research`, `context`, `netadmin`, `hep`, `build`, `call`, `browser`, and `connect` pass directly through to this core runtime. Derived career-graph indexing and run-journal diagnosis are also owned by the installed Hephaestus runtime; Terminal keeps existing project data intact but no longer exposes separate `agentlas career-graph` or `agentlas journal` commands. If no core runtime is found, Agentlas Terminal halts with an explicit error and exit code 1 (no silent fallback). The terminal package owns REPL orchestration, session trees, agent registries, Hub/Cloud HTTP client surfaces, credential storage, MCP preflight probing, automation scheduling, and SQLite schema management. ### Shared State with Agentlas Desktop The launcher (`bin/agentlas.cjs`) runs system Node against `engine/`. The default data directory is identical to Agentlas Desktop's `userData`: | OS | Default Data Path | | --- | --- | | macOS | `~/Library/Application Support/Agentlas` | | Windows | `%APPDATA%\Agentlas` | | Linux | `$XDG_CONFIG_HOME/Agentlas` (default `~/.config/Agentlas`) | The SQLite database file is `agentlas.sqlite` (`user_version=106`). When launched for the first time without an existing database, it bootstraps schemas using `engine/bootstrap-schema.sql`. Consequently, **projects, installed agents, task history, automation sessions, and MCP registrations are shared across Desktop and Terminal**. The first ordered project agent remains the controller; additional agents are task-scoped and are stored only as execution ledgers, never as global conversations or durable owners. **Single migration authority.** The Desktop app owns the schema migration ladder; the CLI never migrates the shared database. `engine/bootstrap-schema.sql` is generated by running that ladder to completion against an empty database, so a CLI-created store already sits at the ladder head and has nothing left for Desktop to upgrade. If the CLI opens a store older than the version it knows, it refuses with an actionable message instead of migrating or silently proceeding — a second migrator on this lock-free file is what corrupted the store once before. On a machine with no Desktop app, an operator can set `AGENTLAS_STORE_MIGRATION_ROLE=owner` for a single deliberate upgrade run with every other Agentlas process closed. SQLite driver priority: `better-sqlite3` (optional dependency native build), then Node 22+ `node:sqlite` when the first driver is unavailable. ### Hub Installation & Safety Policy Local installation of Hub agents is gated by `assertHubInstallAllowed` (`engine/hub/install.cjs`). Installation is restricted in the following scenarios: - **Cloud-callable / Call-only Agents**: Local install blocked. Use via `agentlas call `. Owners restore via `agentlas cloud restore `. - **Packages without Instructions**: Blocked if required instruction manifests are missing. - **Untrusted Trust Grades**: Packages with trust grade lower than A/B require explicit side-load overrides. - **Web-only Agents**: Blocked on terminal surface. - **Withdrawn Catalog Items**: Fails with `Hub agent not found`. Package uploads (`upload`) default to private owner-scoped Agent Cloud storage; public Hub publishing requires explicit `--visibility marketplace`. ## Desktop-Only Surface Scope The following GUI-specific features are reserved for Agentlas Desktop and are not exposed in the terminal CLI: - Telegram bot token issuance & port configuration (`agentlas telegram` is read-only) - Visual project-team composition and ordering - Interactive GUI approval sheets & browser popups - Custom MCP server addition GUI (Terminal supports listing & `mcp probe`) - Site Studio, T-rex slide studio, Prompt Store GUI - Mobile pairing QR sheets & Quests - Provider quota dashboards & visual marketplace browsing ## Environment Variables | Variable | Description | | --- | --- | | `AGENTLAS_USER_DATA_DIR` | Custom data directory override (default: shared Desktop `userData`) | | `AGENTLAS_LANG` | Preferred locale (`ko` \| `en`) — overrides system `LANG` | | `AGENTLAS_MAX_PARALLEL` | Maximum concurrent execution sessions (default: 4, max: 16) | | `AGENTLAS_SESSION` | Agentlas Cloud session cookie token | | `AGENTLAS_WEB_BASE_URL` | Base URL for Web services (default: `https://agentlas.cloud`) | | `AGENTLAS_MCP_BASE_URL` | Base URL for Hub MCP APIs (default: `/api/mcp/v1`) | | `HEPHAESTUS_BIN` / `HEPHAESTUS_RUNTIME_ROOT` | Custom path to Agentlas OS core runtime | | `AGENTLAS_MODEL_MAX_TIER` | Max model tier cap for swarms (`economy` \| `balanced` \| `frontier`) | | `NO_COLOR` | Disables ANSI color output if non-empty (`FORCE_COLOR=1` forces color on) | ## Troubleshooting & Diagnostics ```sh agentlas doctor # Checks database, PATH runtimes, active CLI drivers, and cloud session agentlas --where # Outputs JSON diagnostic of launcher, engine, DB paths, driver, and Node version ``` - **`no_runtime: no agent CLI found`**: Connect Antigravity and put `agy` on `PATH` first, or install `claude`/`codex`; `gemini` remains available as a legacy CLI. Kimi, Grok, and Cursor use the shared ACP driver when their local CLIs are available. - **`runtime '' has no v2 streaming driver yet`**: Specified `--runtime` is not supported for active execution. Supported values: `claude-code`, `codex`, `agy` (Antigravity), `gemini` (legacy). - **`Node vX — Node 22+ (node:sqlite) is required when better-sqlite3 is unavailable`**: `better-sqlite3` native build failed on Node 20/21. Upgrade to Node 22+ or install build tools for native compilation. - **`storm`/`context`/`hep` halting due to missing runtime**: Agentlas OS core runtime is missing. Install Agentlas OS or set `HEPHAESTUS_BIN=`. - **`'xxx' is not an agentlas command`**: Typo guard intercepted an unrecognized command. Use `agentlas run -p "xxx"` to run it as a prompt. ## Development & Verification Engine source code resides in `engine/*.cjs`. ```sh sh test/smoke.sh # Runs surface tests, guard tests, fresh DB tests, contract tests & parity gates npm run smoke # Equivalent to npm run test:release-contracts node scripts/gen-bootstrap-schema.cjs # Regenerates engine/bootstrap-schema.sql from the Desktop ladder (never reads a live store) ``` Smoke tests run isolated inside a temporary `AGENTLAS_USER_DATA_DIR` and do not touch local user data. ## Release & Security Allowlist Published package versions on npm are governed strictly by OIDC trusted publisher workflows (`.github/workflows/npm-publish.yml`). Release verification enforces tag identity (`vX.Y.Z`), contract tests, smoke tests, and manifest allowlists preventing non-release files (development tests, fixtures, internal documents) from being packaged into npm artifacts. Detailed release logs and source-to-registry boundaries are documented in [CHANGELOG.md](CHANGELOG.md). **Ordering rule: the Desktop release must ship before the terminal core that requires it.** The terminal vendors the Desktop app's compiled core and reads its shipped `PRAGMA user_version` into `engine/bootstrap-schema.sql` (`node scripts/gen-bootstrap-schema.cjs`); at runtime it refuses to touch a shared store older than that (`engine/core/store-schema.cjs`, `AGENTLAS_STORE_SCHEMA_TOO_OLD`). That refusal is honest but only safe if the Desktop release carrying that schema is already in users' hands — the Desktop app is a separate, manually-triggered release (`agentlas_desktop/.github/workflows/ release-signed-mac.yml`), so it can lag behind what the terminal's vendored core now requires. `npm run verify:desktop-release-order` (wired into `prepublishOnly` and `test/smoke.sh`) enforces this: it compares the schema the vendored core requires against `desktopCompatibleRelease`/ `desktopCompatibleSchemaVersion` declared in `engine/vendor/desktop-core.manifest.json` — the Desktop release the terminal claims is already shipped — and fails the terminal release if the core needs a newer schema than that. **Ship the Desktop release first, then update those two manifest fields (`node scripts/write-desktop-core-manifest.cjs --desktop-release vX.Y.Z --desktop-schema-version N …`), then publish the terminal.** ## License [Apache-2.0](LICENSE) — Agentlas Terminal is the independent terminal runtime for the [Agentlas OS](https://github.com/agentlas-ai/Agentlas-OS) package contract.