Agents

An agent is a runtime identity plus isolated state. It has an ID (agt_...), display name, system files, model config, skills, channels, scheduler, and sessions.

Create an Agent

fastclaw agents init alpha \
  --provider openai \
  --model openai/gpt-4o-mini \
  --api-key-env OPENAI_API_KEY

Agents created through the CLI appear in the dashboard, and agents created in the dashboard are addressable from the CLI. There is one store per FASTCLAW_HOME.

Resolve Agents

CLI commands accept either display name or ID:

fastclaw agents config alpha get
fastclaw agents config agt_d3c4a5 get

If text matches one agent's ID and another agent's display name, FastClaw reports ambiguity instead of guessing.

Agent System Files

Allowed filenames:

SOUL.md
IDENTITY.md
USER.md
BOOTSTRAP.md
MEMORY.md
HEARTBEAT.md
AGENTS.md
TOOLS.md
agent.json

Manage them with:

fastclaw agents files ls alpha
fastclaw agents files put alpha SOUL.md ./SOUL.md
fastclaw agents files get alpha MEMORY.md ./MEMORY.md

Config Overrides

Per-agent config is saved at scope=agent under the agent ID:

fastclaw agents config alpha set model openai/gpt-4o-mini
fastclaw agents config alpha set temperature 0.7
fastclaw agents config alpha set sandbox.enabled true

Common keys:

• model
• temperature
• maxTokens
• thinking
• policy
• sandbox, sandbox.enabled, sandbox.backend, sandbox.image, sandbox.network

Public Access

The dashboard's Edit Agent dialog includes a Public access toggle. When enabled, anyone with /agents/{id}/chat/ can chat with the agent under their own account. Sessions, memory, and USER.md remain partitioned per chatter; SOUL.md, IDENTITY.md, skills, and model defaults are shared from the owner.