update /tmp refs to /usr
Alessandro committed
Feb 10, 2026 at 14:36 UTC
12e6ef4b33adc2a9198a07d6997be22d68d0981c
9 files changed
+62
-63
docs/advanced/architecture.md
+4
-4
@@ -53,8 +53,8 @@ This architecture ensures:
53
| `/python/helpers` | Utility functions |
54
| `/python/tools` | Tool implementations |
55
| `/tmp` | Temporary runtime data |
56
-| `/tmp/chats` | Saved chat history (JSON) |
57
-| `/tmp/secrets.env` | Secrets store (not always included in backups) |
56
+| `/usr/chats` | Saved chat history (JSON) |
57
+| `/usr/secrets.env` | Secrets store (not always included in backups) |
58
| `/usr/projects` | Project workspaces and `.a0proj` metadata |
59
| `/webui` | Web interface components |
60
| `/webui/css` | Stylesheets |
@@ -65,8 +65,8 @@ This architecture ensures:
65
### Key Files
66
| File | Description |
67
| --- | --- |
68
-| `tmp/settings.json` | Main runtime settings (written by the Settings UI) |
69
-| `tmp/secrets.env` | Secrets store (managed via Settings -> Secrets) |
68
+| `usr/settings.json` | Main runtime settings (written by the Settings UI) |
69
+| `usr/secrets.env` | Secrets store (managed via Settings -> Secrets) |
70
| `conf/model_providers.yaml` | Model provider defaults and settings |
71
| `agent.py` | Core agent implementation |
72
| `initialize.py` | Framework initialization |
docs/advanced/connectivity.md
+4
-4
@@ -499,7 +499,7 @@ Retrieve file contents by paths, returning files as base64 encoded data. Useful
499
### API Reference
500
501
**Parameters:**
502
-* `paths` (array, required): Array of file paths to retrieve (e.g., `["/a0/tmp/uploads/file.txt"]`)
502
+* `paths` (array, required): Array of file paths to retrieve (e.g., `["/a0/usr/uploads/file.txt"]`)
503
504
**Headers:**
505
* `X-API-KEY` (required)
@@ -553,8 +553,8 @@ async function getFiles(filePaths) {
553
554
// Example 1: Get specific files
555
const filePaths = [
556
- "/a0/tmp/uploads/document.txt",
557
- "/a0/tmp/uploads/data.json"
556
+ "/a0/usr/uploads/document.txt",
557
+ "/a0/usr/uploads/data.json"
558
];
559
getFiles(filePaths);
560
@@ -581,7 +581,7 @@ async function attachmentWorkflow() {
581
console.log('Message sent with attachment');
582
583
// Step 2: Retrieve the uploaded file
584
- const retrievedFiles = await getFiles(["/a0/tmp/uploads/test.txt"]);
584
+ const retrievedFiles = await getFiles(["/a0/usr/uploads/test.txt"]);
585
586
if (retrievedFiles && retrievedFiles["test.txt"]) {
587
const originalContent = atob(retrievedFiles["test.txt"]);
docs/development/extensibility.md
+1
-1
@@ -230,7 +230,7 @@ Agent Zero supports creating specialized subagents with customized behavior. The
230
- `/agents/{agent_profile}/prompts/` - for custom prompts
231
- `/agents/{agent_profile}/settings.json` - for agent-specific configuration overrides
232
233
-The `settings.json` file for an agent uses the same structure as `tmp/settings.json`, but you only need to specify the fields you want to override. Any field omitted from the agent-specific `settings.json` will continue to use the global value.
233
+The `settings.json` file for an agent uses the same structure as `usr/settings.json`, but you only need to specify the fields you want to override. Any field omitted from the agent-specific `settings.json` will continue to use the global value.
234
235
This allows power users to, for example, change the AI model, context window size, or other settings for a single agent without affecting the rest of the system.
236
docs/getting-started/installation.md
+31
-32
@@ -462,6 +462,24 @@ ollama rm <model-name>
462
463
---
464
465
+## How to Update Agent Zero
466
+
467
+> [!NOTE]
468
+> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances.
469
+
470
+### Recommended Update Process (Docker)
471
+
472
+1. **Keep the old container running** and note its port.
473
+2. **Pull the new image** (`agent0ai/agent-zero:latest`).
474
+3. **Start a new container** on a different host port.
475
+4. In the **old** instance, open **Settings → Backup & Restore** and create a backup.
476
+5. In the **new** instance, restore that backup from the same panel.
477
+
478
+> [!TIP]
479
+> If the new instance fails to load settings, remove `/a0/usr/settings.json` and restart to regenerate default settings.
480
+
481
+---
482
+
483
## Using Agent Zero on Your Mobile Device
484
485
Agent Zero can be accessed from mobile devices and other computers using the built-in **Tunnel feature**.
@@ -496,38 +514,6 @@ For developers or users who need to run Agent Zero directly on their system, see
514
515
---
516
499
-## How to Update Agent Zero
500
-
501
-> [!NOTE]
502
-> Since v0.9, Agent Zero includes a Backup & Restore workflow in the Settings UI. This is the **safest** way to upgrade Docker instances.
503
-
504
-### Recommended Update Process (Docker)
505
-
506
-1. **Keep the old container running** and note its port.
507
-2. **Pull the new image** (`agent0ai/agent-zero:latest`).
508
-3. **Start a new container** on a different host port.
509
-4. In the **old** instance, open **Settings → Backup & Restore** and create a backup.
510
-5. In the **new** instance, restore that backup from the same panel.
511
-6. **Manually copy secrets** from `/a0/tmp/secrets.env` if you rely on them (secrets are not always included in backups).
512
-
513
-> [!TIP]
514
-> If the new instance fails to load settings, remove `/a0/tmp/settings.json` and restart to regenerate defaults.
515
-
516
-### Manual Migration (Legacy or Non-Docker)
517
-
518
-If you are migrating from older, non-Docker setups, copy these directories into your new instance:
519
-
520
-- `/a0/memory` (agent memories)
521
-- `/a0/knowledge` (custom knowledge)
522
-- `/a0/instruments` (custom instruments)
523
-- `/a0/tmp/settings.json` (settings)
524
-- `/a0/tmp/chats/` (chat history)
525
-- `/a0/tmp/secrets.env` (secrets)
526
-
527
-Then proceed with the Docker installation steps above.
528
-
529
----
530
-
517
## Advanced: Automated Configuration via Environment Variables
518
519
Agent Zero settings can be automatically configured using environment variables with the `A0_SET_` prefix in your `.env` file. This enables automated deployments without manual configuration.
@@ -576,6 +562,19 @@ docker run -p 50080:80 \
562
563
---
564
565
+### Manual Migration (Legacy or Non-Docker)
566
+
567
+If you are migrating from older, non-Docker setups, copy these directories into `/a0/usr/` in the new instance:
568
+
569
+- `/a0/memory` (agent memories)
570
+- `/a0/knowledge` (custom knowledge)
571
+- `/a0/instruments` (custom instruments)
572
+- `/a0/tmp/settings.json` (settings)
573
+- `/a0/tmp/chats/` (chat history)
574
+- `/a0/tmp/secrets.env` (secrets)
575
+
576
+Then proceed with the Docker installation steps above.
577
+
578
## Conclusion
579
580
After following the instructions for your specific operating system, you should have Agent Zero successfully installed and running. You can now start exploring the framework's capabilities and experimenting with creating your own intelligent agents.
docs/getting-started/mcp-setup.md
+9
-9
@@ -18,7 +18,7 @@ MCP servers are external processes or services that expose a set of tools that A
18
Agent Zero discovers and integrates MCP tools dynamically:
19
20
1. **Configuration**: You define the MCP servers Agent Zero should connect to in its configuration. The primary way to do this is through the Agent Zero settings UI.
21
-2. **Saving Settings**: When you save your settings via the UI, Agent Zero updates the `tmp/settings.json` file, specifically the `"mcp_servers"` key.
21
+2. **Saving Settings**: When you save your settings via the UI, Agent Zero updates the `usr/settings.json` file, specifically the `"mcp_servers"` key.
22
3. **Server Startup**: Agent Zero initializes configured MCP servers (stdio servers) or connects to them (remote servers). For `npx`/`uvx` based servers, the first run may download packages.
23
4. **Tool Discovery**: Upon initialization (or when settings are updated), Agent Zero connects to each configured and enabled MCP server and queries it for the list of available tools, their descriptions, and expected parameters.
24
5. **Dynamic Prompting**: The information about these discovered tools is then dynamically injected into the agent's system prompt. A placeholder like `{{tools}}` in a system prompt template (e.g., `prompts/agent.system.mcp_tools.md`) is replaced with a formatted list of all available MCP tools. This allows the agent's underlying Language Model (LLM) to know which external tools it can request.
@@ -52,17 +52,17 @@ The primary method for configuring MCP servers is through **Agent Zero's setting
52
53
When you input and save your MCP server details in the UI, these settings are written to:
54
55
-* `tmp/settings.json`
55
+* `usr/settings.json`
56
57
-### The `mcp_servers` Setting in `tmp/settings.json`
57
+### The `mcp_servers` Setting in `usr/settings.json`
58
59
-Within `tmp/settings.json`, the MCP servers are defined under the `"mcp_servers"` key.
59
+Within `usr/settings.json`, the MCP servers are defined under the `"mcp_servers"` key.
60
61
* **Value Type**: The value for `"mcp_servers"` must be a **JSON formatted string**. The string itself contains either:
62
* A JSON object containing `"mcpServers"` (recommended, matches the Settings UI)
63
* A JSON array of server configuration objects
64
* **Default Value**: An empty config (for example, `{"mcpServers": {}}`).
65
-* **Manual Editing (Advanced)**: While UI configuration is recommended, you can also manually edit `tmp/settings.json`. If you do, ensure the `"mcp_servers"` value is a valid JSON string, with internal quotes properly escaped.
65
+* **Manual Editing (Advanced)**: While UI configuration is recommended, you can also manually edit `usr/settings.json`. If you do, ensure the `"mcp_servers"` value is a valid JSON string, with internal quotes properly escaped.
66
67
**Example `mcp_servers` configuration (recommended format):**
68
@@ -80,13 +80,13 @@ Within `tmp/settings.json`, the MCP servers are defined under the `"mcp_servers"
80
}
81
}
82
```
83
-*Note: In `tmp/settings.json`, the entire value of `"mcp_servers"` is stored as a single string. The Settings UI handles escaping automatically.*
83
+*Note: In `usr/settings.json`, the entire value of `"mcp_servers"` is stored as a single string. The Settings UI handles escaping automatically.*
84
85
* **Updating**: As mentioned, the recommended way to set or update this value is through Agent Zero's settings UI.
86
-* **For Existing `settings.json` Files (After an Upgrade)**: If you have an existing `tmp/settings.json` from a version of Agent Zero prior to MCP server support, the `"mcp_servers"` key will likely be missing. To add this key:
86
+* **For Existing `settings.json` Files (After an Upgrade)**: If you have an existing `usr/settings.json` from a version of Agent Zero prior to MCP server support, the `"mcp_servers"` key will likely be missing. To add this key:
87
1. Ensure you are running a version of Agent Zero that includes MCP server support.
88
2. Run Agent Zero and open its settings UI.
89
- 3. Save the settings (even without making changes). This action will write the complete current settings structure, including a default `"mcp_servers": ""` if not otherwise populated, to `tmp/settings.json`. You can then configure your servers via the UI or by carefully editing this string.
89
+ 3. Save the settings (even without making changes). This action will write the complete current settings structure, including a default `"mcp_servers": ""` if not otherwise populated, to `usr/settings.json`. You can then configure your servers via the UI or by carefully editing this string.
90
91
### MCP Server Configuration Structure
92
@@ -147,7 +147,7 @@ Here are templates for configuring individual servers within the `mcp_servers` c
147
}
148
```
149
150
-**Example `mcp_servers` value in `tmp/settings.json`:**
150
+**Example `mcp_servers` value in `usr/settings.json`:**
151
152
```json
153
{
docs/guides/troubleshooting.md
+2
-2
@@ -15,7 +15,7 @@ This page addresses frequently asked questions (FAQ) and provides troubleshootin
15
- No. ChatGPT Plus does not include API credits. You must provide an OpenAI API key in Settings.
16
17
**5. Where is chat history stored?**
18
-- Chat history lives at `/a0/tmp/chats/` inside the container.
18
+- Chat history lives at `/a0/usr/chats/` inside the container.
19
20
**6. How do I integrate open-source models with Agent Zero?**
21
Refer to the [Choosing your LLMs](installation.md#installing-and-using-ollama-local-models) section for configuring local models (Ollama, LM Studio, etc.).
@@ -30,7 +30,7 @@ Use **Settings → Backup & Restore** and avoid mapping the entire `/a0` directo
30
The built-in browser agent is currently unstable on some systems. Use MCP alternatives such as Browser OS, Chrome DevTools, or Playwright. See [MCP Setup](mcp_setup.md).
31
32
**9. My secrets disappeared after a backup restore.**
33
-Secrets are stored in `/a0/tmp/secrets.env` and are not always included in backup archives. Copy them manually.
33
+Secrets are stored in `/a0/usr/secrets.env` and are not always included in backup archives. Copy them manually.
34
35
**10. Where can I find more documentation or tutorials?**
36
- Join the Agent Zero [Skool](https://www.skool.com/agent-zero) or [Discord](https://discord.gg/B8KZKNsPpj) community.
docs/guides/usage.md
+5
-5
@@ -58,7 +58,7 @@ Located beneath the chat input box, Agent Zero provides a set of action buttons
58
Access the chat history in JSON format
59
- View the conversation as processed by the LLM
60
- Useful for debugging and understanding agent behavior
61
- - Files are stored under `/a0/tmp/chats/` inside the container
61
+ - Files are stored under `/a0/usr/chats/` inside the container
62
63
64
@@ -175,7 +175,7 @@ Use the Settings → **Secrets** and **Variables** fields to store credentials a
175
You can reference these values in prompts by name. For example, store `MY_GMAIL` as a secret and instruct the agent to use it when prompted.
176
177
> [!IMPORTANT]
178
-> Secrets are stored in `/a0/tmp/secrets.env`. Keep a manual copy if you rely on backups, as secrets are not always preserved by Backup & Restore.
178
+> Secrets are stored in `/a0/usr/secrets.env`.
179
180
> [!NOTE]
181
> Project-scoped secrets and variables (when using Projects) live under `/a0/usr/projects/<project_name>/.a0proj/` (`secrets.env`, `variables.env`).
@@ -306,7 +306,7 @@ By default, Agent Zero backs up your most important data:
306
* **Uploaded Files**: Documents and files you've worked with
307
308
> [!NOTE]
309
-> Chat history is stored at `/a0/tmp/chats/` inside the container.
309
+> Chat history is stored at `/a0/usr/chats/` inside the container.
310
311
#### Customizing Backup Content
312
Before creating a backup, you can customize what to include:
@@ -327,7 +327,7 @@ Before creating a backup, you can customize what to include:
327
328
> [!NOTE]
329
> Backup creation may take a few minutes depending on the amount of data. You'll see progress updates during the process.
330
-> Secrets stored in `/a0/tmp/secrets.env` are not always included in backup archives. Keep a manual copy if you rely on secrets.
330
+> Secrets stored in `/a0/usr/secrets.env` are not always included in backup archives. Keep a manual copy if you rely on secrets.
331
332
### Restoring from Backup
333
The restore process allows you to recover your Agent Zero setup from a previous backup:
@@ -374,7 +374,7 @@ Optionally clean up existing files before restoring:
374
* **Test Restores**: Occasionally test restoring backups to ensure they work
375
376
#### Security Considerations
377
-* **Secrets**: Backups do **not** reliably include `/a0/tmp/secrets.env`. Copy it manually when migrating.
377
+* **Secrets**: Backups do **not** reliably include `/a0/usr/secrets.env`. Copy it manually when migrating.
378
* **Secure Storage**: Store backup files securely and don't share them
379
* **Clean Systems**: When restoring on new systems, verify all configurations
380
docs/quickstart.md
+2
-2
@@ -1,5 +1,5 @@
1
# Quick Start
2
-This guide provides a quick introduction to using Agent Zero. We'll cover the essential installation steps and running your first task.
2
+This guide provides a quick introduction to using Agent Zero. We'll cover the essential installation steps and running your first Skill.
3
4
## Installation Steps
5
@@ -91,7 +91,7 @@ Now that you've run a simple task, you can experiment with more complex requests
91
* Explore web development tasks
92
* Develop A0 itself
93
94
-### [Open Usage Guide](usage.md)
94
+### [Open A0 Usage Guide](usage.md)
95
96
Provides more in-depth information on tools, projects, tasks, and backup/restore.
97
knowledge/main/about/installation.md
+4
-4
@@ -302,15 +302,15 @@ For developers or users who need to run Agent Zero directly on their system,see
302
- `/memory` - Agent's memory
303
- `/knowledge` - Custom knowledge base (if you imported any custom knowledge files)
304
- `/instruments` - Custom instruments and functions (if you created any custom)
305
- - `/tmp/settings.json` - Your Agent Zero settings
306
- - `/tmp/chats/` - Your chat history
305
+ - `/usr/settings.json` - Your Agent Zero settings
306
+ - `/usr/chats/` - Your chat history
307
- Once you have saved these files and directories, you can proceed with the Docker runtime [installation instructions above](#windows-macos-and-linux-setup-guide) setup guide.
308
- Reach for the folder where you saved your data and copy it to the new Agent Zero folder set during the installation process.
309
- Agent Zero will automatically detect your saved data and use it across memory, knowledge, instruments, prompts and settings.
310
311
> [!IMPORTANT]
312
-> If you have issues loading your settings, you can try to delete the `/tmp/settings.json` file and let Agent Zero generate a new one.
313
-> The same goes for chats in `/tmp/chats/`, they might be incompatible with the new version
312
+> If you have issues loading your settings, you can try to delete the `/usr/settings.json` file and let Agent Zero generate a new one.
313
+> The same goes for chats in `/usr/chats/`, they might be incompatible with the new version
314
315
2. **Update Process (Docker Desktop)**
316
- Go to Docker Desktop and stop the container from the "Containers" tab