AgentUse: Open-source agent runtime

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_DIR=/path/to/profile`	Process	Override the directory containing user-global config, env, managed projects, plugins, and skills
`AGENTUSE_CONFIG=/path/to/config.json`	Process	Deprecated file-level config override; compatibility only
`AGENTUSE_ENV=/path/to/.env`	Process	Deprecated file-level env override; compatibility only
`ABOUT.md`	Directory	Optional dashboard identity and description for the project or folder containing it
`.agentuse/plugins/*.{ts,js}`	Project	Project-local plugins
`$AGENTUSE_CONFIG_DIR/plugins/*.{ts,js}`	User	User-global plugins; defaults to `~/.agentuse/plugins/*.{ts,js}`
`.agentuse/skills/`	Project	Project-local skills
`$AGENTUSE_CONFIG_DIR/skills/`	User	User-global skills; defaults to `~/.agentuse/skills/`
`.claude/skills/`	Project	Claude ecosystem skill compatibility
`~/.claude/skills/`	User	Claude ecosystem skill compatibility
`~/.agents/skills/`	User	Shared agent skills compatibility
`{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:

---
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 for the full schema. Approval channels are configured separately from approval policy:

approval: true
channels:
  slack:
    events: [approval]
    channel_id: C0123456789

See Channels for event semantics and 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:

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.

Never commit .env, .env.local, or other secret-bearing environment files.

See Environment Variables for supported variables and examples.

Global serve config

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

{
  "serve": {
    "projects": [
      { "path": "~/work/projA" },
      { "id": "b", "path": "~/work/projB" }
    ],
    "default": "projA",
    "port": 12233,
    "host": "127.0.0.1",
    "auth": true,
    "logFile": true,
    "hideAgentSource": false,
    "brand": { "name": "Acme Operations" },
    "terms": {
      "project": "workspace",
      "folder": "team|teams"
    }
  }
}

Use AGENTUSE_CONFIG_DIR=/path/to/profile to isolate the complete configuration profile. AgentUse reads config.json and .env from that directory and uses its projects/, plugins/, and skills/ subdirectories for user-global resources. Project paths inside config.json may start with ~ or ~/. AGENTUSE_CONFIG and AGENTUSE_ENV remain as deprecated file-level overrides for compatibility and take precedence over AGENTUSE_CONFIG_DIR when set. They are scheduled for removal no earlier than December 1, 2026; new integrations should use only AGENTUSE_CONFIG_DIR. 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
`serve.hideAgentSource`	boolean	Hide raw `.agentuse` source in the dashboard and `/api/agents/detail`; capability summaries (model, tools, schedule) stay visible. For deployments where visitors may run and observe agents but should not read their instructions (demos, client sandboxes)
`serve.brand.name`	string	Your company name, shown beside the AgentUse wordmark, in page titles, and as the installed app name (max 60 chars)
`serve.terms.project`	string	Dashboard display noun for a project. Routes, API fields, and CLI output keep the technical name
`serve.terms.folder`	string	Dashboard display noun for a folder. Add an explicit plural as `singular	plural` for irregular nouns

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`
`serve.hideAgentSource`	`--hide-agent-source` sets it to `true` (the flag can only hide, never re-expose a config that hides)

AGENTUSE_API_KEY remains env-only and is not read from config. See Webhooks and CLI Commands for serve usage.

Directory identity with `ABOUT.md`

Place an optional ABOUT.md in a served project root or a directory containing agents. The dashboard uses the file to label and describe that directory. It does not alter agent prompts, API routes, or scheduling. Plain Markdown becomes the longer body shown on the directory detail surface:

Automations owned by the Revenue Operations team.

Optional YAML frontmatter supplies compact display fields:

---
name: Revenue Operations
description: Pipeline and renewal automations
owner: Operations Platform
---

These agents reconcile CRM events and prepare renewal follow-ups.

Recognized frontmatter keys are name, description, and owner; scalar string or numeric values are normalized for display. Unknown keys and other value types are ignored. The body remains the longer description. AgentUse rejects symlinked and oversized ABOUT.md files so directory identity cannot disclose an unrelated local file or inflate API responses. serve.brand.name labels the whole deployment; ABOUT.md labels one served directory within it. Use serve.terms when the deployment calls projects or folders by different nouns.

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:

{
  "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.

Model defaults and aliases

A models block in ~/.agentuse/config.json sets the model used by agent files that omit model, and names models that agent files reference as @name:

{
  "models": {
    "default": "anthropic:claude-sonnet",
    "aliases": {
      "fast": "anthropic:claude-haiku",
      "smart": "anthropic:claude-opus",
      "cheap-dev": "openai:gpt-mini:dev",
      "judgment": {
        "candidates": ["anthropic:claude-opus", "openai:gpt"],
        "cooldown": "5m"
      }
    }
  }
}

---
model: "@fast"
---

default applies to any agent file with no model: field. AGENTUSE_MODEL overrides it, and an explicit model: in the file overrides both.
aliases keys are alphanumeric with hyphens or underscores, referenced with the @ sigil (define fast, write @fast). The @ is required in the reference because a bare name is already a valid OpenAI model id.
A string value may be a concrete id, a version alias, another @name, or any of those with an :env auth suffix.
An object value defines ordered fallback candidates. AgentUse tries the next candidate on a transient first-request failure (rate limit, timeout, provider 5xx, or transport failure) or when the candidate cannot be authenticated at all (no login, an OAuth token that will not refresh, a 401/403), and only if the model has not produced output or invoked a tool in the current execution segment. The resolved order is persisted so the same policy remains available after an approval resume.
Optional cooldown is a duration string such as "30s" or "5m". A concrete model that just failed this way is skipped by new runs in the same process until the cooldown expires. Cooldowns are in memory: restarting agentuse serve or starting a separate CLI process resets them.

Aliases are resolved when the agent file is parsed. A fallback alias keeps its ordered concrete candidates until execution. Session logs, cost accounting, and context limits record the concrete model that actually ran. A suspended run first resumes on its last selected model, even if the alias has since changed, and can advance through the remaining persisted candidates if that resumed segment fails before producing new output or invoking a tool. To point a repo at its own aliases rather than your user-global ones, put config.json in a dedicated directory and set AGENTUSE_CONFIG_DIR to that directory. Run agentuse models to see every alias and what it currently resolves to.

Plugins

Loose plugins are TypeScript or JavaScript modules loaded from these directories:

.agentuse/plugins/*.{ts,js}
$AGENTUSE_CONFIG_DIR/plugins/*.{ts,js} (defaults to ~/.agentuse/plugins/*.{ts,js})

Project plugins load before user-global plugins. Installed global packages are recorded under $AGENTUSE_DATA_DIR/plugins, which defaults to ~/.local/share/agentuse/plugins. Plugins installed with agentuse plugins install -l live under .agentuse/packages and are recorded in .agentuse/plugins.json. See Plugins for the plugin API.

Skills

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

.agentuse/skills/
$AGENTUSE_CONFIG_DIR/skills/ (defaults to ~/.agentuse/skills/)
.claude/skills/
~/.claude/skills/
~/.agents/skills/

Use .agentuse/skills/ for project-specific skills and $AGENTUSE_CONFIG_DIR/skills/ for personal skills shared across projects. The latter defaults to ~/.agentuse/skills/. The .claude/skills/ locations provide compatibility with existing Claude skills, while ~/.agents/skills/ supports the shared agent-skills convention. Symlinked skill directories and SKILL.md files are supported; dangling links are skipped and circular directory links are ignored safely. See 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}.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
`$AGENTUSE_DATA_DIR/`	AgentUse runtime	Credentials, sessions, learnings, schedules, registry, logs, push, telemetry, and update state; defaults to `~/.local/share/agentuse/`

Configuration and durable application data have separate roots. AGENTUSE_CONFIG_DIR moves user-controlled configuration; AGENTUSE_DATA_DIR moves AgentUse-owned data. XDG_DATA_HOME remains a compatible base-directory fallback. Isolated test or development servers should set the two AgentUse-specific variables. State that a run generates rather than a person writes lives outside the project, under a per-project directory keyed by a digest of the git root:

$AGENTUSE_DATA_DIR/project/{project-hash}/
├── session/          # execution logs
├── learnings/        # agent learnings, one file per agent
└── consolidations/   # undo snapshots for `agentuse learnings tidy`

Learnings moved here in v0.17.0; they used to sit beside the agent file as {agent-file}.learnings.md, where every run rewrote them into your working tree. agentuse learnings <agent-file> --path prints the new location and agentuse learnings migrate --all moves existing files into it. See Learning, Store, Sandbox, and Session Storage for details.

Getting Started

Building

Running

Reference

Configuration Files

Quick reference

Agent files

Environment files

Global serve config

Directory identity with `ABOUT.md`

Global env defaults

Model defaults and aliases

Plugins

Skills

Generated files and data locations

​Quick reference

​Agent files

​Environment files

​Global serve config

​Directory identity with ABOUT.md

​Global env defaults

​Model defaults and aliases

​Plugins

​Skills

​Generated files and data locations

Quick reference

Agent files

Environment files

Global serve config

Directory identity with `ABOUT.md`

Global env defaults

Model defaults and aliases

Plugins

Skills

Generated files and data locations