Trust Levels
The 4-tier agent permission scheme — what each level can read and write.
Source of truth: static/docs/integration-guide.md in the OSS repo. The numeric values shown here are the canonical values stored in the agents.trust_level column (SmallInteger, default 1).
The 4 tiers
| Level | Name | Permissions |
|---|---|---|
| 0 | restricted | No read or write access. Use to temporarily disable an agent. |
| 1 | standard | Read and write within own fleet only. Default for new agents. |
| 2 | cross_fleet | Read across all fleets in the tenant; write within own fleet only. |
| 3 | admin | Read and write across all fleets; can delete memories. |
Agent registration
Two paths put an agent in the system:
Atomic provisioning (recommended for production)
POST /api/v1/admin/agent-keys/provision mints an agent-scoped credential and creates the Agent row in a single round-trip. You set initial_trust and initial_fleet in the request body and skip the lazy-create flow entirely. The response carries agent_row_created: true plus the raw mc_ key (returned exactly once — save it). The credential's mc_ prefix is shared with tenant-scoped keys; scope is bound at mint time on the credential row. Confirm with GET /api/v1/whoami using the new credential.
See Per-agent keys for the end-to-end curl + Python flow.
Lazy auto-registration (legacy / OSS-only fallback)
Agents that connect with a tenant mc_ key (or a self-hosted standalone deployment) are auto-registered on their first memclaw_write. The fleet_id from that first write becomes the agent's home fleet.
The starting trust level depends on a tenant setting (agents.require_agent_approval in tenant_settings):
- Default —
require_agent_approval = false: new agent starts at trust 1 (standard) and can read + write in its home fleet immediately. require_agent_approval = true: new agent starts at trust 0 (restricted) — recall and write both fail with403until an operator promotes the agent via the dashboard orPATCH /api/agents/{agent_id}/trust.
Source: core-api/src/core_api/services/agent_service.py (get_or_create_agent) plus DEFAULT_TRUST_LEVEL in core-api/src/core_api/constants.py.
Enforcement
Trust is checked on every API call. A level-1 agent attempting a cross-fleet recall gets 403. The admin API key (ADMIN_API_KEY) bypasses trust enforcement entirely.
Changing trust levels
From the dashboard (admin role required) or via the API:
Via API:
curl -X PATCH "$API/api/agents/{agent_id}/trust?tenant_id=$TENANT" \
-H "X-API-Key: $ADMIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"trust_level": 2}'See the API reference for the full set of agent endpoints.
Architecture
The services that make up MemClaw, what each one is responsible for, and how a write flows from client through core-api, the event bus, the worker, and storage.
Cross-tenant credentials
Read across every tenant in your org with a single credential — for admin agents, analytics, and rollups.