Agent1 is a local-first AI workspace for running a central orchestrator, local worker agents, and permissioned external collaborators from one desktop surface.
The current app centers on the Hybrid Collaboration Workspace: create a project, choose how Agent1 should coordinate the work, attach local or external agents, then talk to Agent1 from the command box while approvals and activity stream through the workspace.
- 🧭 Hybrid Collaboration Workspace: project-first desktop UI with a central Agent1 canvas, local systems lane, external agents lane, activity feed, and command composer.
- 🗂️ Project workflow: create and select projects, keep the active project remembered, and switch collaboration mode from the header.
- 🎛️ Agent1 orchestration: Agent1 is the central user-facing controller. Click the Agent1 node to choose provider and model from available dropdowns.
- 🧑💻 Local agents: add local worker agents, configure provider/model, and delete agents with a custom confirmation dialog.
- 🌐 External agents and MCP servers: invite or connect external systems from the right lane for project-scoped collaboration.
- 🛡️ Permissions and approvals: local tools use explicit permission policies, external agents use project-scoped permissions, and pending approvals appear in the activity area.
- 🧠 Model providers: supports OpenCode, Ollama, OpenAI-compatible endpoints, and NVIDIA NIM.
- ⚡ Live runtime: sessions, events, approvals, projects, and model options are served through the local API.
- 🧠 Persistent memory: semantic vector storage with cosine similarity search. Agent1 recalls relevant past outcomes before planning.
- 📊 Hierarchical planning: decompose goals into main steps with nested sub-steps, executed as independent sub-plans.
- 🔄 Self-critique loop: each step is reviewed by a critic agent before marking complete.
- 💡 Proactive suggestions: system generates follow-up suggestions for failed or incomplete steps, surfaced in the Memory panel.
-
🚦 Start the API server
cargo run --bin agent1 -- server --bind 127.0.0.1:17371
-
🖥️ Open the desktop app
cd desktop npm install npm run tauri:dev
For browser-only development:
cd desktop npm run dev
Then open
http://localhost:1420. -
✨ Create a project
Use
+ Create Project, enter a project name, and choose a collaboration mode:Mode Use When 🤖 AutomaticLet Agent1 choose the coordination style based on context. 📋 StructuredYou want a plan, delegated execution, and review. 🚀 FastYou want lower-overhead parallel work. 🛡️ CarefulYou want more approval checkpoints before actions. -
🔐 Choose permissions
Use conservative permissions first:
- 🧰 Give local agents only the tools they need, such as file read, file list, search, memory, or MCP access.
- 🚧 Keep file write and shell-style capabilities denied unless the task requires them.
- 🪪 For external agents, prefer project-scoped permissions: read blackboard, write blackboard, create artifacts, allowed tools, delegation, and max concurrent tasks.
- ✅ Review approval prompts in the activity feed before allowing sensitive actions.
-
🎚️ Configure Agent1
Click the central
A1node, choose a provider and model from the dropdowns, then save. The setup window closes after saving. -
🤝 Add collaborators
- 🧑💻 Use
+ Add Agentfor local workers. - 🌍 Use
+ Invite Externalfor external agents or MCP-backed systems. - 🗑️ Delete local agents from their lane when they are no longer needed.
- 🧑💻 Use
-
💬 Run work
Type into
Agent1 Commandand pressRun. Agent1 handles the request, records the session, streams activity, and coordinates available agents according to the active project mode.
| Layer | Location | Purpose |
|---|---|---|
| 🖼️ Desktop UI | desktop/ |
React/Tauri Hybrid Collaboration Workspace. |
| 🧩 CLI/API | crates/agent1-cli/ |
Local API server, CLI commands, routes, and app bootstrap. |
| ⚙️ Runtime | crates/agent1-runtime/ |
Agent session execution, tools, approvals, events, and failure handling. |
| 🧠 Models | crates/agent1-models/ |
OpenCode, Ollama, OpenAI-compatible, and NVIDIA NIM model adapters. |
| 🗄️ Database | crates/agent1-db/ |
SQLite persistence for agents, sessions, projects, events, approvals, and collaboration records. |
| 🧭 Collaboration | crates/agent1-collab/ |
Project state, collaboration modes, blackboard, tasks, and external agent records. |
| 🌉 Gateway | crates/agent1-gateway/ |
Invite-token flow and project-scoped external agent access. |
| 🧠 Memory | crates/agent1-memory/ |
Semantic vector storage with cosine similarity search for persistent memory and suggestions. |
| 🎯 Orchestrator | crates/agent1-orchestrator/ |
Hierarchical planning, step execution, self-critique loop, and memory integration. |
| Endpoint | Description |
|---|---|
🩺 GET /api/health |
Check the local API server. |
🧑💻 GET /api/agents |
List local agents, including Agent1. |
➕ POST /api/agents |
Create or update a local agent. |
🗑️ DELETE /api/agents/{agent_id} |
Delete a local agent. Agent1 cannot be deleted. |
🧠 GET /api/models |
List available models by provider. |
🗂️ GET /api/projects |
List collaboration projects. |
✨ POST /api/projects |
Create a project with a collaboration mode. |
🎛️ PATCH /api/projects/{id} |
Update project settings such as collaboration mode. |
🪪 POST /api/projects/{id}/invite |
Generate an external invite token for a project. |
🌐 GET /api/projects/{id}/externals |
List external agents for a project. |
🧾 GET /api/projects/{id}/blackboard |
Read project blackboard entries. |
✅ GET /api/projects/{id}/tasks |
List collaboration tasks. |
📬 POST /api/projects/{id}/tasks |
Submit a collaboration task. |
💬 POST /api/sessions/run |
Run Agent1 or another agent. |
🔎 GET /api/sessions/{id}/trace |
Inspect messages, events, tool calls, and approvals for a session. |
⚡ GET /ws/events |
Receive live runtime events. |
🔍 GET /api/memory?query=... |
Search semantic memory for relevant past outcomes. |
✍️ POST /api/memory |
Write a new memory entry. |
💡 GET /api/suggestions |
List pending proactive suggestions. |
💡 POST /api/suggestions/{id}/accept |
Accept a suggestion. |
💡 POST /api/suggestions/{id}/dismiss |
Dismiss a suggestion. |
| Command | What It Does |
|---|---|
🚦 agent1 server |
Start the local API server. |
💬 agent1 run --agent agents/assistant.toml --task "hello" |
Run an agent from the CLI. |
👥 agent1 team --task "..." |
Run planner, worker, and critic agents. |
🔁 agent1 loop --task "..." --max-runs 5 |
Run bounded autonomous plan, execute, review iterations with persistent notes. |
🔁 agent1 loops list |
List registered recurring loops from .agent1/loops.toml. |
🔁 agent1 loops run external-intelligence |
Run one registered loop through the bounded autonomous loop runner. |
🧠 agent1 models --provider ollama |
List models for a provider. Use --provider nvidia for NVIDIA NIM. |
➕ agent1 agent create agents/my-agent.toml |
Save an agent definition. |
🧰 agent1 mcp list |
List MCP servers. |
📚 agent1 sessions |
List recent sessions. |
⚡ agent1 events |
List recent runtime events. |
Orchestrated runs route roles independently. By default every role uses Ollama llama3.1:8b, but you can override globally or per role:
$env:AGENT1_MODEL_DEFAULT = "llama3.1:8b"
$env:AGENT1_MODEL_CRITIC = "qwen2.5-coder:14b"
$env:AGENT1_MODEL_PLANNER_PROVIDER = "openai_compatible"
$env:AGENT1_MODEL_PLANNER_BASE_URL = "http://localhost:8000/v1"Supported role suffixes are PLANNER, WORKER, CRITIC, RESEARCHER, BUILDER, REPORTER, and ORCHESTRATOR. Each role also supports _PROVIDER, _BASE_URL, and _CONTEXT overrides.
🧠 OpenCode is available as a provider in the Agent1 configuration dropdown. On Windows, Agent1 launches the OpenCode Node entrypoint directly to avoid shell argument issues with opencode.cmd.
🦙 Run Ollama locally, then configure Agent1 or a worker agent with provider ollama.
ollama serve🔌 Optional base URL:
$env:OLLAMA_BASE_URL = "http://localhost:11434"🌐 Use this for local or hosted OpenAI-compatible servers:
$env:OPENAI_BASE_URL = "http://localhost:8000/v1"🚀 Agent1 supports NVIDIA NIM through the OpenAI-compatible chat completions and models APIs. Set your NVIDIA API key before starting the API server or desktop app:
$env:NVIDIA_API_KEY = "nvapi-..."
cargo run --bin agent1 -- models --provider nvidiaThe default NVIDIA base URL is https://integrate.api.nvidia.com/v1. Agent definitions should use provider nvidia and one of the model IDs returned by the model listing command or the desktop dropdown.
🩺 Confirm the API is running:
Invoke-RestMethod http://127.0.0.1:17371/api/health🔎 Check Agent1's provider/model from the central A1 configuration panel. Then inspect recent sessions and events:
cargo run --bin agent1 -- sessions
cargo run --bin agent1 -- events🔄 Refresh the desktop. Projects are persisted in SQLite and the UI remembers the active project.
🧹 Restarting the API marks interrupted running sessions as failed, so stale sessions should not keep the Active counter stuck.
🚪 Start the API on another local port:
cargo run --bin agent1 -- server --bind 127.0.0.1:17372🎛️ Then update the desktop API base setting.
- 🏠 Agent1 binds the API to localhost for local-first use.
- 🗄️ Project, session, agent, and approval data are stored locally in SQLite.
- 🛡️ Tool use is permissioned; sensitive actions should remain approval-gated.
- 🪪 External agents are project-scoped and should be granted only the permissions needed for the current project.