Agent Tools

OpenLegion ships a set of @skill-decorated built-in tools organized into modules under engine/src/agent/builtins/. Worker agents see a curated subset based on their permissions.json ACL; the operator agent sees additional control-plane tools. Agents can also create custom skills at runtime (AST-validated) and use MCP tool servers. Every tool call has a default OPENLEGION_TOOL_TIMEOUT of 300s.

​

Execution

​

File Operations

All file operations are scoped to /data with 4-stage path-traversal protection. Limits: _MAX_READ=500_000 bytes, _MAX_LIST_ENTRIES=500. Direct writes to workspace files (SOUL/INSTRUCTIONS/USER/MEMORY/HEARTBEAT/AGENTS/INTERFACE) are blocked at this layer — use update_workspace instead.

​

HTTP

SSRF protection is enforced at the mesh: DNS pinning, RFC1918 / loopback / link-local / CGNAT / 6to4 / Teredo / IPv4-mapped-IPv6 blocking, fail-closed on DNS error, max 5 redirects (re-validated at each hop), cross-origin auth strip.

​

Browser Automation

Camoufox (stealth Firefox fork) per agent, lazy-spawned on X displays :100..:163 (64 slots) paired with KasmVNC ports 6100..6163. The browser-service container is shared (FastAPI :8500); the Camoufox instance is per-agent. All browser actions are parallel_safe=False per agent_id. Costs for CAPTCHA solving are tracked in millicents (1/100,000 USD) with per-agent + per-tenant monthly caps and a fleet-wide CAPTCHA_DISABLED kill switch. Solver-provider circuit breaker: 3 failures / 5 min → open 10 min. Session persistence is opt-in (BROWSER_SESSION_PERSISTENCE_ENABLED, default FALSE; snapshot interval 60-3600s, default 300s). Device profiles: desktop-windows (default), desktop-macos, mobile-ios, mobile-android. Mobile profiles spoof UA strings only — the underlying Camoufox / Firefox engine and TLS/JA3 fingerprints remain desktop. Fingerprint burn detection uses a rolling window of 10; ≥50% rejection sets fingerprint_burn=True. There is no auto-rotation — the operator must rotate the profile and reset.

​

Memory

Vector search uses text-embedding-3-small (OpenAI, 1536 dims). Non-OpenAI providers default to "none" and degrade to keyword-only; after 3 consecutive embedding failures the store silently disables vectors for the process lifetime. See the Memory System for full details on the 5-layer architecture.

​

Web Search

​

Image Generation

​

Fleet Awareness

​

Workspace

Workspace caps (returned 413 on overflow): SOUL 4K, INSTRUCTIONS 12K, USER 4K, MEMORY 16K, INTERFACE 4K, AGENTS 12K, HEARTBEAT uncapped. PROJECT.md and SYSTEM.md are bootstrap-only and read-only at runtime.

​

Introspection

​

Shared State (Blackboard)

All blackboard operations are subject to per-agent blackboard_read / blackboard_write glob patterns. Writes are CAS-based via write_if_version.

​

Coordination

Coordination uses the durable V2 task ledger when OPENLEGION_ORCHESTRATION_TASKS_V2=1 (default ON); V1 falls back to blackboard tasks/{agent}/{handoff_id} records.

​

Scheduling

5-field cron (minute granularity) or every N[s/m/h/d] interval syntax. No 6-field / seconds support. Three modes: message-mode (LLM dispatch), tool-mode (tool_name / tool_params direct invoke — no LLM), and heartbeat-mode (heartbeat=true). Heartbeats default to every 15m (the operator’s is force-locked to every 15m) and have a skip-LLM optimization that activates only when (not manual) + (HEARTBEAT.md is default) + (no recent activity) + (no probes triggered). See Triggering & Automation for details.

​

Skills Management

​

Subagent Spawning

Subagents have MAX_DEPTH=2, MAX_CONCURRENT=3 per parent, default TTL 300s (max 600s), DEFAULT_MAX_ITERATIONS=10. Subagents cannot recurse, cannot create skills, and cannot use the browser concurrently (browser module is parallel-unsafe per agent).

​

Credential Vault

Agents never see raw secret values — only opaque $CRED{name} handles that the mesh substitutes at call time. System-tier credentials (OPENLEGION_SYSTEM_*) are always blocked from agents regardless of allowed_credentials.

​

Wallet

EVM chains (evm:ethereum, evm:base, evm:arbitrum, evm:polygon, evm:sepolia) and Solana (solana:mainnet, solana:devnet). Per-agent EVM keys derive via BIP-44 (m/44'/60'/{agent_index}'/0/0); per-agent Solana keys via HMAC-SHA512 over a PBKDF2 of the master seed. Private keys never leave the mesh process. The master seed is returned once at POST /api/wallet/init with Cache-Control: no-store; GET /api/wallet/seed returns HTTP 410 Gone afterward. Defaults: LIMIT_PER_TX_USD=10, LIMIT_DAILY_USD=100, RATE_LIMIT_PER_HOUR=10. Agents need can_use_wallet=true — and the operator cannot grant this flag; it must be edited directly in permissions.json.

​

Operator-Only Tools

The operator agent has additional control-plane tools for fleet management. These are not available to worker agents. Hard / soft edit fields. SOFT (5-min Undo): instructions, soul, heartbeat, heartbeat_schedule, interface, role. HARD (30-min confirmation): model, permissions, budget, thinking.