> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration Files

> User-facing files and directories that configure AgentUse

AgentUse reads configuration from agent files, environment files, global defaults, and project or user-level extension directories.

## Quick reference

| Path                                   | Scope       | Purpose                                                                                |
| -------------------------------------- | ----------- | -------------------------------------------------------------------------------------- |
| `*.agentuse`                           | Agent       | Defines an agent with YAML frontmatter and Markdown instructions                       |
| `.env.local`                           | Project     | Local environment variables loaded before `.env` when present                          |
| `.env`                                 | Project     | Environment variables for API keys, model providers, MCP servers, and runtime behavior |
| `--env-file <path>`                    | Run command | Load a specific environment file for `agentuse run`                                    |
| `~/.agentuse/config.json`              | User        | Global `agentuse serve` defaults and an `env` block of variable defaults               |
| `AGENTUSE_CONFIG=/path/to/config.json` | Process     | Override the global config file path                                                   |
| `.agentuse/plugins/*.{ts,js}`          | Project     | Project-local plugins                                                                  |
| `~/.agentuse/plugins/*.{ts,js}`        | User        | User-global plugins                                                                    |
| `.agentuse/skills/`                    | Project     | Project-local skills                                                                   |
| `~/.agentuse/skills/`                  | User        | User-global skills                                                                     |
| `.claude/skills/`                      | Project     | Claude ecosystem skill compatibility                                                   |
| `~/.claude/skills/`                    | User        | Claude ecosystem skill compatibility                                                   |
| `{agent-name}.learnings.md`            | Agent       | Auto-created learning notes for agents with learning enabled                           |
| `{agent-name}.store.json`              | Agent       | Persistent store file for agents with store enabled                                    |

## Agent files

Agent files use the `.agentuse` extension. They combine YAML frontmatter with Markdown instructions:

```yaml theme={"system"}
---
model: anthropic:claude-sonnet-5
description: Summarize pull requests
schedule: "0 9 * * 1"
tools:
  bash:
    commands:
      - "gh *"
---

Review open pull requests and summarize anything blocked.
```

Common frontmatter fields include `model`, `tools`, `schedule`, `mcpServers`, `subagents`, `store`, `learning`, `sandbox`, `approval`, `channels`, `timeout`, and `maxSteps`.

See [Agent Syntax](/reference/agent-syntax) for the full schema.

Approval channels are configured separately from approval policy:

```yaml theme={"system"}
approval: true
channels:
  slack:
    events: [approval]
    channel_id: C0123456789
```

See [Channels](/guides/channels) for event semantics and [Approval Gates](/guides/approval-gates) for the approval dashboard and API workflow.

## Environment files

AgentUse loads environment variables from the project root. Project roots are detected by walking upward from the starting directory until `.agentuse/`, `.git/`, or `package.json` is found. If none are found, the starting directory is the project root.

For `agentuse run`, `.env.local` takes priority when present, otherwise `.env` is used. You can also pass a specific file:

```bash theme={"system"}
agentuse run agent.agentuse --env-file .env.production
```

For `agentuse serve`, `-C` selects the directory whose agents are served, while the detected project root owns `.env.local`, `.env`, `.agentuse/store`, and session state. Each served project loads its own `.env.local` or `.env` in that project's worker process. Environment variables do not mix across served projects.

Use environment files for provider API keys, MCP server credentials, and runtime controls such as `MAX_STEPS`, `LOG_LEVEL`, and `AGENTUSE_TELEMETRY_DISABLED`.

<Warning>
  Never commit `.env`, `.env.local`, or other secret-bearing environment files.
</Warning>

See [Environment Variables](/reference/environment-variables) for supported variables and examples.

## Global serve config

Put long-lived `agentuse serve` defaults in `~/.agentuse/config.json`:

```json theme={"system"}
{
  "serve": {
    "projects": [
      { "path": "~/work/projA" },
      { "id": "b", "path": "~/work/projB" }
    ],
    "default": "projA",
    "port": 12233,
    "host": "127.0.0.1",
    "auth": true,
    "logFile": true
  }
}
```

Use `AGENTUSE_CONFIG=/path/to/config.json` to load a different file. Project paths may start with `~` or `~/`.

AgentUse runs one serve daemon at a time. Put every project that should accept `/run`, approval, and notification traffic into `serve.projects`, or pass repeated `-C` flags when starting the daemon.

| Config key       | Type    | Description                                                                                                          |
| ---------------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `serve.projects` | array   | Directories to serve agents from. Each item needs `path`; AgentUse detects the project root upward; `id` is optional |
| `serve.default`  | string  | Default project id when `POST /run` omits `project`                                                                  |
| `serve.port`     | number  | Port to listen on                                                                                                    |
| `serve.host`     | string  | Host to bind to                                                                                                      |
| `serve.auth`     | boolean | Require API key authentication for exposed hosts                                                                     |
| `serve.logFile`  | boolean | Write serve logs to a file                                                                                           |

CLI flags override config values:

| Config key       | CLI override                                           |
| ---------------- | ------------------------------------------------------ |
| `serve.projects` | `-C, --directory` replaces the configured project list |
| `serve.default`  | `--default <id>`                                       |
| `serve.port`     | `--port <number>`                                      |
| `serve.host`     | `--host <string>`                                      |
| `serve.auth`     | `--no-auth` sets auth to `false`                       |
| `serve.logFile`  | `--no-log-file` sets log files to `false`              |

`AGENTUSE_API_KEY` remains env-only and is not read from config.

See [Webhooks](/guides/webhooks) and [CLI Commands](/reference/cli-commands#agentuse-serve) for serve usage.

## Global env defaults

Alongside `serve`, `~/.agentuse/config.json` accepts an `env` block of environment variable defaults, mirroring the `env` key in Claude Code's `settings.json`. Use it for non-secret defaults you want applied to every run without maintaining a separate `~/.agentuse/.env` file:

```json theme={"system"}
{
  "env": {
    "AGENTUSE_MOCK_MODEL": "anthropic:claude-haiku-4-5"
  }
}
```

Values must be strings. The block is applied at startup and **never overrides a variable that is already set**, so the precedence is:

```
shell env  >  ~/.agentuse/.env  >  config.json "env"
```

Per-command flags still win over all of these. For example, `--mock-model <model>` overrides `AGENTUSE_MOCK_MODEL` from any source, and `--mock` is satisfied by a mock model coming from the flag, the shell, `~/.agentuse/.env`, or the config `env` block.

Keep secrets (like `AGENTUSE_API_KEY` and provider API keys) in an environment file rather than `config.json`, which is plain non-secret configuration.

## Plugins

Plugins are TypeScript or JavaScript modules loaded from these directories:

1. `.agentuse/plugins/*.{ts,js}`
2. `~/.agentuse/plugins/*.{ts,js}`

Project plugins load before user-global plugins.

See [Plugins](/guides/plugins) for the plugin API.

## Skills

Skills are reusable instruction packs stored as `SKILL.md` files. AgentUse discovers skills in this order:

1. `.agentuse/skills/`
2. `~/.agentuse/skills/`
3. `.claude/skills/`
4. `~/.claude/skills/`

Use `.agentuse/skills/` for project-specific skills and `~/.agentuse/skills/` for personal skills shared across projects. The `.claude/skills/` locations provide compatibility with existing Claude skills.

See [Skills](/guides/skills) for authoring and discovery details.

## Generated files and data locations

These files are generated by features rather than hand-written as primary configuration:

| Path                        | Created by      | Purpose                                                             |
| --------------------------- | --------------- | ------------------------------------------------------------------- |
| `{agent-name}.learnings.md` | Learning        | Stores extracted guidance next to the agent file by default         |
| `{agent-name}.store.json`   | Store           | Stores persistent key-value data for the agent                      |
| `.agentuse/sandbox/`        | Sandbox         | Stores sandbox-related working data                                 |
| `.agentuse/benchmark/`      | Benchmark       | Stores local benchmark suites and results                           |
| `$XDG_DATA_HOME/agentuse/`  | Session logging | Stores execution sessions, defaulting to `~/.local/share/agentuse/` |

See [Learning](/guides/learning), [Store](/guides/store), [Sandbox](/guides/sandbox), and [Session Storage](/reference/session-storage) for details.