AgentUse: Open-source agent runtime

AgentUse supports variable placeholders in agent files (both YAML frontmatter and markdown content) to make your agent definitions more flexible and secure.

Available Variables

Variable	Syntax	Usage Locations	Description
Project Root	`${root}`	Filesystem paths, System prompt	Expands to the project root directory
Agent Directory	`${agentDir}`	Filesystem paths, System prompt	Expands to the directory containing the agent file
Temp Directory	`${tmpDir}`	Filesystem paths, System prompt	Expands to the system temp directory
Environment Variable	`${env:VAR_NAME}`	`mcpServers.<name>.auth.token` only	Expands to the value of an environment variable

${env:VAR_NAME} is intentionally NOT supported in the system prompt (markdown content) to prevent accidental secret exposure to the LLM.

To show path-placeholder syntax literally in the model prompt instead of resolving it, escape the dollar sign with a backslash: \${root} becomes the literal text ${root}. This is useful when an agent reviews or authors another AgentUse file. The escape applies to ${root}, ${agentDir}, and ${tmpDir}; it does not enable environment-variable expansion.

`${root}` - Project Root

The ${root} variable expands to your project’s root directory, which is detected by looking for markers like .git, package.json, or .agentuse directory.

Usage

Use ${root} in filesystem tool path configurations to reference paths relative to your project root, regardless of where you run the agent from.

---
model: anthropic:claude-sonnet-5
tools:
  filesystem:
    - path: ${root}/src
      permissions: [read, write]
    - paths:
        - ${root}/docs
        - ${root}/tests
      permissions: [read]
---

Benefits

Portable: Paths work regardless of current working directory
Consistent: Always references the same location relative to project
Safe: Restricts file access to defined project paths

`${agentDir}` - Agent Directory

The ${agentDir} variable expands to the directory containing the agent file. This is useful for referencing files bundled with your agent.

Usage

Use ${agentDir} to access files that are distributed alongside your agent file, such as scripts, configs, or data files.

---
model: anthropic:claude-sonnet-5
tools:
  filesystem:
    - path: ${agentDir}/scripts
      permissions: [read]
    - path: ${agentDir}/data
      permissions: [read, write]
---

Benefits

Self-contained agents: Bundle resources with your agent file
Relocatable: Agent works regardless of where it’s installed
No absolute paths: Avoid hardcoding paths in agent definitions

${agentDir} is only available when the agent is loaded from a file. If the agent is loaded from a string or other source, this variable will not be resolved.

`${tmpDir}` - Temp Directory

The ${tmpDir} variable expands to the system’s temporary directory (os.tmpdir()).

Usage

Use ${tmpDir} for temporary file storage that doesn’t need to persist across agent runs.

---
model: anthropic:claude-sonnet-5
tools:
  filesystem:
    - path: ${tmpDir}/agentuse
      permissions: [read, write]
---

Benefits

Platform-independent: Works on macOS, Linux, and Windows
No cleanup needed: Temp files are typically cleaned by the OS
Safe for scratch work: Ideal for intermediate processing files

`${env:VAR_NAME}` - Environment Variables

The ${env:VAR_NAME} syntax allows you to reference environment variables in your configuration. This is particularly useful for sensitive values like API tokens.

Usage

Currently supported in HTTP MCP server authentication:

---
model: anthropic:claude-sonnet-5
mcpServers:
  api_server:
    url: https://api.example.com/mcp
    auth:
      type: bearer
      token: ${env:API_TOKEN}
    requiredEnvVars:
      - API_TOKEN  # Validates the variable exists before connecting
---

How It Works

When the agent starts, ${env:API_TOKEN} is replaced with process.env.API_TOKEN
If the environment variable is not set, a warning is logged
Use requiredEnvVars to ensure the variable exists before the agent runs

Security Benefits

No hardcoded secrets: Tokens stay in environment variables, not in code
Version control safe: .agentuse files can be committed without exposing secrets
Explicit requirements: requiredEnvVars documents what’s needed to run the agent

Variables in System Prompt

You can use path variables (${root}, ${agentDir}, ${tmpDir}) in the markdown content (system prompt) of your agent file. This helps the agent understand its environment.

Usage

---
model: anthropic:claude-sonnet-5
tools:
  filesystem:
    - path: ${root}/data
      permissions: [read, write]
---

You are a data processing agent.

## Your Environment

- Project root: ${root}
- Agent location: ${agentDir}
- Temp workspace: ${tmpDir}

You have read/write access to the project's data directory.

When the agent runs, these variables are resolved to actual paths, so the agent receives:

You are a data processing agent.

## Your Environment

- Project root: /home/user/my-project
- Agent location: /home/user/my-project/agents
- Temp workspace: /tmp

You have read/write access to the project's data directory.

Security Note

${env:VAR_NAME} is not supported in the system prompt to prevent accidental secret exposure. Environment variables should only be used for authentication tokens in MCP server configuration, where they are handled securely and never sent to the LLM.

Examples

Complete Agent with All Path Variables

---
model: anthropic:claude-sonnet-5
description: "Agent with multiple filesystem paths"
tools:
  filesystem:
    - path: ${root}/data
      permissions: [read, write]
    - path: ${agentDir}/templates
      permissions: [read]
    - path: ${tmpDir}/workspace
      permissions: [read, write]
mcpServers:
  external_api:
    url: https://api.example.com/mcp
    auth:
      type: bearer
      token: ${env:EXTERNAL_API_KEY}
    requiredEnvVars:
      - EXTERNAL_API_KEY
---

You are an agent with access to project files, bundled templates, and temp workspace.

Self-Contained Agent with Bundled Resources

---
model: anthropic:claude-sonnet-5
description: "Agent with bundled scripts and data"
tools:
  filesystem:
    - path: ${agentDir}/scripts
      permissions: [read]
    - path: ${agentDir}/prompts
      permissions: [read]
    - path: ${tmpDir}/output
      permissions: [read, write]
---

You have access to bundled scripts in ./scripts and prompt templates in ./prompts.
Write output files to the temp workspace.

Multiple Environment Variables

mcpServers:
  service_a:
    url: https://a.example.com/mcp
    auth:
      type: bearer
      token: ${env:SERVICE_A_TOKEN}
    requiredEnvVars:
      - SERVICE_A_TOKEN

  service_b:
    url: https://b.example.com/mcp
    auth:
      type: bearer
      token: ${env:SERVICE_B_TOKEN}
    requiredEnvVars:
      - SERVICE_B_TOKEN

Variable Resolution

Variables are resolved at different times:

Variable	Resolution Time	Scope
`${root}`	Agent initialization	Filesystem paths, System prompt
`${agentDir}`	Agent initialization	Filesystem paths, System prompt
`${tmpDir}`	Agent initialization	Filesystem paths, System prompt
`${env:VAR_NAME}`	MCP connection setup	HTTP auth tokens only

Troubleshooting

Variable not expanding

Ensure you’re using the correct syntax:

Project root: ${root} (lowercase)
Agent directory: ${agentDir} (camelCase)
Temp directory: ${tmpDir} (camelCase)
Environment variables: ${env:VAR_NAME} (with env: prefix)

The old ${VAR_NAME} syntax without the env: prefix is not supported.

agentDir not resolving

${agentDir} is only available when the agent is loaded from a file path. It will not resolve when:

The agent is loaded from a URL
The agent is loaded from a string
The agent file path is not passed to the runner

In these cases, ${agentDir} will remain as literal text and path validation may fail.

Environment variable not found

If you see a warning about an environment variable not being set:

Check that the variable is exported in your shell or defined in .env
Verify the variable name matches exactly (case-sensitive)
Add the variable to requiredEnvVars for early validation

Path not resolving correctly

If ${root} isn’t pointing to the expected directory:

Ensure your project has a recognizable marker (.git, package.json, etc.)
Run the agent from within your project directory
Use agentuse run -C /path/to/project to specify the project root

Next Steps

Agent Syntax

Complete YAML configuration reference

Environment Variables

All environment variables used by AgentUse

Getting Started

Building

Running

Reference

Variables

Available Variables

`${root}` - Project Root

Usage

Benefits

`${agentDir}` - Agent Directory

Usage

Benefits

`${tmpDir}` - Temp Directory

Usage

Benefits

`${env:VAR_NAME}` - Environment Variables

Usage

How It Works

Security Benefits

Variables in System Prompt

Usage

Security Note

Examples

Complete Agent with All Path Variables

Self-Contained Agent with Bundled Resources

Multiple Environment Variables

Variable Resolution

Troubleshooting

Next Steps

Agent Syntax

Environment Variables

​Available Variables

​${root} - Project Root

​Usage

​Benefits

​${agentDir} - Agent Directory

​Usage

​Benefits

​${tmpDir} - Temp Directory

​Usage

​Benefits

​${env:VAR_NAME} - Environment Variables

​Usage

​How It Works

​Security Benefits

​Variables in System Prompt

​Usage

​Security Note

​Examples

​Complete Agent with All Path Variables

​Self-Contained Agent with Bundled Resources

​Multiple Environment Variables

​Variable Resolution

​Troubleshooting

​Next Steps

Agent Syntax

Environment Variables

Available Variables

`${root}` - Project Root

Usage

Benefits

`${agentDir}` - Agent Directory

Usage

Benefits

`${tmpDir}` - Temp Directory

Usage

Benefits

`${env:VAR_NAME}` - Environment Variables

Usage

How It Works

Security Benefits

Variables in System Prompt

Usage

Security Note

Examples

Complete Agent with All Path Variables

Self-Contained Agent with Bundled Resources

Multiple Environment Variables

Variable Resolution

Troubleshooting

Next Steps