Onboarding

What you get at the end

• A running CLAIIM control plane (backend + admin UI)
• An AI Org -- the organisational boundary for your agents
• A Skill -- the versioned rulebook for what an agent can and cannot do
• A Policy -- an org-wide rule that enforces ALLOW or DENY
• A provisioned agent with a real token
• A gate test proving ALLOW and DENY work correctly
• A Chron log entry for each gate decision with accountability anchor

The gate model:

Your agent code
    |
    |  "I want to do X"
    v
CLAIIM gate
    |-- Is this agent active?
    |-- Does its Skill permit X?
    |-- Does any Policy override the answer?
    |-- Write to Chron (always, regardless of outcome)
    v
ALLOW or DENY returned to agent

The gate is inline and fail-closed. If CLAIIM is not reachable, agents cannot act. This is by design.

Before you begin

Complete the Install Guide first. You need CLAIIM running and the health check returning status: ok.

For the manual gate test (Step 10 Option B), you also need Python 3.10+.

End-to-end walkthrough

1. 1

   Start CLAIIM

   If you used Docker Compose, run docker compose up -d. Verify the backend is healthy:

   curl http://localhost:8181/health
   # Expected: {"status":"ok"}

   The bundled Docker Compose Postgres is for evaluation convenience only. For production deployments, set DATABASE_URL in .env to your own PostgreSQL instance. Your database is yours -- Chron records, agent identities, gate decisions, and policy definitions never leave your environment.
2. 2

   Log in

   Open http://localhost:3001. The migration seeds two accounts:

   Account	Email	Password
   Primary admin	admin@claiim.io	claiim-demo
   Peer admin	peer@claiim.io	claiim-demo

   Log in as admin@claiim.io. You land on the Agents page.

   Change these passwords before any production use. The peer account exists for PIM approval -- see Step 3.
3. 3

   Understand PIM -- read this, do not skip it

   CLAIIM enforces Privileged Identity Management (PIM) for all control-plane operations: creating AI Orgs, skills, policies, and provisioning agents.

   PIM is two-person control. One admin requests an elevated session and states a reason. A second admin reviews and approves. Only then can the requester perform privileged operations. Both sides are logged in Chron.

   This is not optional and cannot be bypassed. It is the safety architecture for the control plane itself. In this onboarding you will use the two seeded accounts to simulate real two-person approval.

4. 4

   Request and approve a PIM session

   In one browser tab (admin@claiim.io):

   • Click PIM in the left navigation
   • Click Request elevation
   • Enter a reason: "Initial onboarding -- setting up first agent fleet"
   • Accept the default duration (1 hour)
   • Click Request -- your request shows as PENDING

   In a second browser tab or incognito window:

   • Log in as peer@claiim.io / claiim-demo
   • Click PIM
   • Click Approve on the pending request

   Back in your first tab, refresh PIM. Your session now shows ACTIVE. You can now create AI Orgs, skills, policies, and agents.

5. 5

   Create an AI Org

   An AIORG is the organisational boundary that agents belong to. It is the scoping primitive for skills, policies, and audit visibility.

   • Click AIORG in the left navigation
   • Click New AIORG
   • Name: Engineering
   • Leave Parent empty (root-level org)
   • Click Create
6. 6

   Accountability anchor

   An accountability anchor is the human user whose identity is attached to every action an agent takes. It closes the "an AI did it" accountability gap.

   For onboarding, admin@claiim.io is the anchor. No extra steps needed -- the admin user already exists in the system. In production, create individual user accounts and assign each agent to the human responsible for it.

7. 7

   Create a Skill

   A Skill is the versioned rulebook for an agent: the email identity it acts as, system prompt, allowed actions, and forbidden actions. Skills are version-controlled -- an agent holds a reference to a specific version. Silently changing what a live agent can do is not possible.

   • Click Skills in the left navigation
   • Click New Skill

   Name	Deploy Bot
   AI Org	Engineering
   Agent Email	deploy-bot@yourcompany.com
   Allowed Actions	deploy:staging
   Forbidden Actions	deploy:production

   • Click Publish Version
   • Note the Skill Version ID -- you will use it in Step 9
8. 8

   Write a Policy

   A Policy is an org-wide rule that the gate enforces regardless of what the Skill says. DENY policies take priority over everything.

   • Click Policies in the left navigation
   • Click New Policy
   • Name: No production deploys
   • Rule: Action deploy:production / Effect DENY / Applies to: All agents
   • Click Create

   This creates a double lock: the Skill already forbids production deploys, and the Policy denies it at org level. Both appear in the Chron record.

9. 9

   Provision an agent

   Provisioning creates the agent record and generates its token.

   • Click Agents in the left navigation
   • Click New Agent
   • AI Org: Engineering
   • Name: Prod Deploy Bot
   • Accountability Anchor: admin@claiim.io
   • Skill: Deploy Bot -- version 1
   • Click Provision

   The token is shown once only. Copy it immediately.
10. 10

    Test the gate

    Option A -- run the full rehearsal (recommended):

    bash rehearsal.sh

    Expected output:

    Action 1: deploy to staging-eu-1
      Requesting CLAIIM approval for  deploy:staging
      ALLOW -- gate cleared (OWN_AIORG)
      Deployed  (simulated)
    
    Action 2: deploy to prod-eu-1
      Requesting CLAIIM approval for  deploy:production
      DENY -- policy deny
      Production deployment blocked. No action taken.

    Option B -- test manually with your own agent token:

    import asyncio, os
    from claiim import CLAIIMClient
    
    async def main():
        client = CLAIIMClient(
            gate_url="http://localhost:8181/v",
            agent_token=os.environ["AGENT_TOKEN"],
            skill_version_id=os.environ["SKILL_VERSION_ID"],
        )
        await client.init()
    
        result = await client.validate("deploy:staging", {"target": "eu-staging-1"})
        print(f"deploy:staging -> {result.outcome}")
    
        try:
            result = await client.validate("deploy:production", {"target": "eu-prod-1"})
            print(f"deploy:production -> {result.outcome}")
        except Exception as e:
            print(f"deploy:production -> DENIED: {e}")
    
    asyncio.run(main())

11. 11

    Read the Chron proof

    Every gate decision is written to Chron immediately.

    • Click Chron in the left navigation
    • You see two entries -- one ALLOW, one DENY
    • Each row shows: time, agent name, action, outcome, accountability anchor, policy version, skill version
    • Expand either row to see full detail

    Chron is append-only. No row can be updated or deleted. This is your audit trail.

After onboarding

• Add more agents and orgs -- create child AIORGs for different teams and provision separate agents with separate skills for each.
• Update a Skill -- click New Version, change the allowed actions, and publish. The existing agent stays on the old version until you explicitly reassign it. There are no silent upgrades.
• Add a cross-AIORG grant -- if an agent in one AIORG needs a skill from another, create a cross-AIORG grant. Both sides must approve. The grant is time-bound and revocable.
• Suspend or decommission -- go to Agents, open the agent detail, and click Suspend (reversible) or Decommission (permanent). The Chron trail is retained permanently.

Common issues