API & Configuration

This page covers the full backend configuration surface for Agent, including startup options, data directory layout, and common troubleshooting guidance.

Data Directory Layout

Agent stores all runtime data under a single data directory:

macOS / Linux: ~/.aiagent/
Windows: %USERPROFILE%\.aiagent\

~/.aiagent/
├── config.yaml              ← Main configuration file (model providers, defaults)
├── workspaces.json          ← Workspace list
├── global_mcp_servers.json  ← Global MCP server configuration
├── workspaces/
│   └── <workspace-id>/
│       ├── workspace.json   ← Workspace metadata
│       ├── mcp_config.json  ← Workspace MCP configuration
│       └── sessions/        ← Session history
├── agent/
│   └── <profile-id>.yaml   ← Agent Profile configuration
├── skills/                  ← User-defined skills
│   └── <skill-name>/
│       └── SKILL.md
└── selfhost/                ← Self-hosted settings (EasyGateway nodes, mTLS certificates)

Configure Model Providers

Configure in the UI (Recommended)

Open Settings → LLM Configuration, add a provider, enter the API key, and choose the default model.

Configure with a File (Ops / Self-hosted)

Edit ~/.aiagent/config.yaml (recommended file permission: 0600):

providers:
  - id: deepseek
    name: DeepSeek
    type: openai          # supported: openai | anthropic | responsemode
    api_key: sk-...
    base_url: https://api.deepseek.com
    enabled: true
    models:
      - id: deepseek-chat
        name: DeepSeek Chat
        context_window: 65536
        supports_thinking: false
        supports_tools: true

  - id: anthropic
    name: Anthropic
    type: anthropic
    api_key: sk-ant-...
    base_url: https://api.anthropic.com
    enabled: true
    models:
      - id: claude-sonnet-4-5
        name: Claude Sonnet 4.5
        context_window: 200000
        max_output_tokens: 16000
        supports_thinking: true
        supports_tools: true

defaults:
  provider: deepseek
  model: deepseek-chat

Supported type values:

type	Description
`openai`	OpenAI-compatible API (DeepSeek, local models, and similar endpoints)
`anthropic`	Native Anthropic API (Claude family)
`responsemode`	OpenAI Responses API (for models such as gpt-4o)

Override with Environment Variables

Environment variables take precedence over file configuration and are useful in containers or CI environments:

export ANTHROPIC_API_KEY=sk-ant-...
export ANTHROPIC_BASE_URL=https://api.anthropic.com
export DEEPSEEK_API_KEY=sk-...

Agent Profile Configuration

Agent Profiles control AI behavior parameters. Each workspace can bind to a different profile.

Profile files are stored at ~/.aiagent/agent/<profile-id>.yaml:

model: "anthropic:claude-sonnet-4-5"   # providerId:modelId

language: zh           # UI language: zh | en | system

timeout_seconds: 18000  # Per-conversation timeout in seconds

thinking:
  enabled: true          # Enable extended thinking mode (requires model support)
  budget: 32000          # Thinking token budget

cache:
  enabled: true          # Enable context cache to reduce repeated token cost
  cache_threshold: 5     # Conversation round threshold before caching starts

compression:
  enabled: true          # Enable automatic context compression to stay within context limits
  threshold_percent: 85  # Trigger compression when context usage reaches this percent (50~95)
  cooldown_seconds: 300  # Minimum interval between compression runs

Start the Backend Service

Basic Startup

./aiagent

Full Example

./aiagent -port 8080 -data ~/.aiagent -mcp <mcp-server-url> -model <default-model>

Flag	Default	Description
`-port`	`8080`	HTTP listen port
`-data`	`~/.aiagent`	Data directory path
`-mcp`	empty	Global MCP server URL
`-model`	empty	Fallback default model (lower priority than `config.yaml`)

Verify Service Health

# Health check (no authentication required)
curl http://localhost:8080/health

# Version info
curl http://localhost:8080/api/version

Pairing agentui with aiagent

When agentui connects to an aiagent backend for the first time, it must claim a local credential from that backend. This pairing step proves that the UI is being operated by someone who can access the target machine.

Typical user flow

Start aiagent and confirm the backend is reachable.
In agentui, enter the backend URL.
agentui calls GET /api/pairing/status.
If the backend is not paired yet, agentui asks for a pairing code.
Read the current pairing code from the local aiagent logs on the target machine, then enter it in agentui.
agentui sends POST /api/pairing/claim with the pairing code.
On success, aiagent marks the node as paired and returns a long-lived credential plus the node_id.
agentui stores that credential locally and uses it for later API and WebSocket access.

Important behavior

The pairing code is a 6-digit code generated by aiagent and is valid for 24 hours.
GET /api/pairing/status returns pairing state such as bound, pairing_required, pairing_expires_at, display_name, and bootstrap_mode.
The status endpoint does not return the pairing code itself. Instead, when the backend is still unpaired, aiagent logs the current pairing code to its local stdout/stderr.
If you are using the macOS desktop app and its bundled local backend, those logs are captured in:

~/Library/Application Support/com.example.agentui/flutter_logs.txt

What happens after pairing

After a successful claim:

protected HTTP APIs accept the returned credential through either:
- Authorization: Bearer <credential>
- X-Aiagent-Credential: <credential>
WebSocket connections can also carry the credential through the agent_credential query parameter
if the user is logged in to a Helix account, agentui may additionally bind that paired node to the cloud account so the credential can be recovered on other devices
if the user is not logged in, the pairing remains local-only on the current device

Advanced / managed deployments

Some managed or containerized deployments use a one-time bootstrap_secret instead of a human-entered pairing code. In that case, agentui still completes pairing through POST /api/pairing/claim, but submits bootstrap_secret rather than pairing_code.

Common errors

400 Bad Request: neither pairing_code nor bootstrap_secret was provided
401 Unauthorized: invalid or expired pairing code / bootstrap secret, or later requests used the wrong credential
409 Conflict: the backend is already paired

If you need to re-pair a machine, rotate credentials, or reset pairing state, see the protected self-host endpoints later on this page.

Workspace-level Configuration

Each workspace can be configured independently:

Bind an Agent Profile: choose a different model and behavior preset
MCP Servers: attach project-specific toolchains
Context Compression: tune trigger strategy based on project scale
Context Cache: control caching timing to reduce API cost

Workspace isolation is the best practice when different projects require different security boundaries, toolchains, or model strategies.

Docker Deployment

# docker-compose.yml
services:
  aiagent:
    image: aiagent:latest
    ports:
      - "8080:8080"
    volumes:
      - ~/.aiagent:/root/.aiagent
    environment:
      - GIN_MODE=release
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - DEEPSEEK_API_KEY=${DEEPSEEK_API_KEY}

GIN_MODE=release reduces HTTP access log verbosity and is better suited for production.

Troubleshooting

Backend Is Not Reachable

Confirm the process is running: ps aux | grep aiagent
Confirm the port and listen address: curl http://localhost:8080/health
Check firewall and network policy settings

Model Provider Errors

Verify that the API key is valid
Confirm that the model ID exists under that provider
Check account quota and access restrictions
Confirm that base_url is correct (do not include a trailing slash)

Workspace Tools Are Not Available

Confirm the workspace directory path is valid
Check that required language marker files exist for code intelligence (for example go.mod, package.json)
Verify that command paths in MCP server configuration are executable

View Logs

The Agent backend logs to stdout/stderr. On macOS desktop, the UI captures backend output and writes it to:

~/Library/Application Support/com.example.agentui/flutter_logs.txt

The most recent 2000 lines are retained.

API Authentication

Administrative APIs require credentials in the request header:

curl http://localhost:8080/api/config/providers \
  -H "X-Aiagent-Credential: <credential>"

The following endpoints do not require authentication and are suitable for health checks and monitoring:

GET /health
GET /api/version
GET /api/pairing/status

Data Directory Layout​

Configure Model Providers​

Configure in the UI (Recommended)​

Configure with a File (Ops / Self-hosted)​

Override with Environment Variables​

Agent Profile Configuration​

Start the Backend Service​

Basic Startup​

Full Example​

Verify Service Health​

Pairing agentui with aiagent​

Typical user flow​

Important behavior​

What happens after pairing​

Advanced / managed deployments​

Common errors​

Workspace-level Configuration​

Docker Deployment​

Troubleshooting​

Backend Is Not Reachable​

Model Provider Errors​

Workspace Tools Are Not Available​

View Logs​

API Authentication​

Related Docs​