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 that allowlists actions; actions without an ALLOW rule are denied
• 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 the Policy allow this action?
    |-- Record the gate decision for Chron processing
    v
ALLOW or DENY returned to agent

This walkthrough tests gate decisions. Your integration must fail closed if the gate is unavailable. Agents with alternate execution routes or credentials can bypass a gate-only integration. See controlled gateway prerequisites.

Before you begin

Complete the Install Guide first. You need CLAIIM running and the readiness check returning status: ready.

For the manual gate test (Step 10), you need Python 3.11+ and the SDK wheel supplied with your identified release candidate. Public package-registry availability is not confirmed; do not rely on an unversioned registry install.

python3 -m venv .venv
. .venv/bin/activate
python -m pip install ./sdk/claiim_sdk-0.1.0-py3-none-any.whl
python -c "from claiim import CLAIIMClient; print('SDK import OK')"

End-to-end walkthrough

1. 1

   Start CLAIIM

   Follow the identified candidate commands in the Install Guide. Verify the backend is healthy:

   curl --fail http://127.0.0.1:18181/readyz
   # Expected: {"status":"ready"}

   The bundled Docker Compose Postgres is for evaluation convenience only. Governance records are stored in your deployment. You control database, export, integration, and support access. Production readiness remains pending.
2. 2

   Log in

   Open http://127.0.0.1:13001/login. Tenant provisioning creates these accounts:

   Account	Email	Password
   Primary admin	admin@claiim.io	Generated password in out/admin.pw
   Peer admin	peer@claiim.io	Generated password in out/admin.pw

   Log in as admin@claiim.io. You land on Home.

   These accounts are explicitly provisioned during candidate installation, not built-in demo logins. This candidate is for evaluation, not production use.
3. 3

   Understand PIM: read this, do not skip it

   CLAIIM uses Privileged Identity Management (PIM) for supported privileged control-plane routes, including skill and policy creation and skill assignment. Organisation proposals use a separate peer-confirmation workflow.

   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.

   PIM protects the supported application control-plane workflow. It does not prevent direct database changes or actions using credentials outside CLAIIM. In this onboarding you will use the two provisioned accounts to exercise two-person approval.

4. 4

   Request and approve a PIM session

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

   • Click Access 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 separate browser profile or incognito window:

   • Log in as peer@claiim.io with the generated password in out/admin.pw
   • Click Access
   • Click Approve on the pending request

   Back in your first tab, refresh PIM. Your session now shows ACTIVE. You can now perform supported privileged operations. Repeat with peer@claiim.io requesting elevation and admin@claiim.io approving it; both administrators need active sessions for the remaining steps.

5. 5

   Select your tenant root

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

   • Click Organizations in the left navigation
   • Select Evaluation, the tenant root created by the Install Guide
   • Use this organisation for the skill, policy and agent below

   Without a licence file, evaluation mode permits one AI Org: this root. Both provisioned administrators are members. Creating a child organisation requires a licence that permits additional AI Orgs and a separate peer confirmation. Continue as peer@claiim.io for the remaining setup.

6. 6

   Accountability anchor

   An accountability anchor is the human user whose identity is attached to every gate decision for an integrated agent. Activity outside CLAIIM is not covered.

   For onboarding, peer@claiim.io is the anchor and a member of the tenant root. The peer 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	Evaluation
   Agent Email	deploy-bot@yourcompany.com
   Allowed Actions	deploy:staging
   Forbidden Actions	deploy:production

   • Press Enter after each action tag, then click Create skill
   • 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. The current gate allows only actions matched by an ALLOW rule; it does not support explicit DENY rules.

   • Click Policies in the left navigation
   • Click New policy and select Evaluation
   • Name: No production deploys
   • Rule 1: Action deploy:staging / Effect ALLOW / Applies to: All agents
   • Do not add deploy:production to the allowlist
   • Press Enter after each action tag, then click Create policy

   The explicit staging ALLOW rule is required. Production is forbidden by the Skill and has no matching policy ALLOW rule, so the gate denies it.

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: Evaluation
   • Name: prod-deploy-bot
   • Skip the optional supervisor for this standalone agent
   • Accountability Anchor: peer@claiim.io
   • Skill: deploy-bot, version 1
   • Advance with Next, review the confirmation, then click Provision agent
   • Click Accept accountability and verify the agent becomes ACTIVE with its skill assigned

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

    Test the gate

    Use the agent token from Step 9 and the Skill Version ID from Step 7. In a Bash terminal, set them without placing the token in shell history:

    read -r -s -p 'Agent token: ' AGENT_TOKEN; printf '\n'
    export AGENT_TOKEN
    read -r -p 'Skill Version ID: ' SKILL_VERSION_ID
    export SKILL_VERSION_ID

    Run the following in Python with the installed SDK:

    import os
    from claiim import (
        CLAIIMClient,
        CLAIIMAuthError,
        CLAIIMDeniedError,
        CLAIIMPendingApprovalError,
        CLAIIMUnavailableError,
    )
    
    client = CLAIIMClient(
        gate_url="http://127.0.0.1:18181/v",
        agent_token=os.environ["AGENT_TOKEN"],
        skill_version_id=os.environ["SKILL_VERSION_ID"],
    )
    
    try:
        client.init()
    except CLAIIMAuthError as error:
        raise SystemExit(f"AUTH ERROR: {error}; no action taken")
    except CLAIIMUnavailableError as error:
        raise SystemExit(f"UNAVAILABLE: {error}; no action taken")
    
    for action, target in (
        ("deploy:staging", "eu-staging-1"),
        ("deploy:production", "eu-prod-1"),
    ):
        try:
            result = client.validate(action_type=action, payload={"target": target})
            print(f"{action} -> {result.outcome}; decision only, no deployment performed")
        except CLAIIMDeniedError as error:
            print(f"{action} -> DENIED: {error}; no action taken")
        except CLAIIMPendingApprovalError as error:
            print(f"{action} -> PENDING APPROVAL: {error.decision_id}; no action taken")
        except CLAIIMAuthError as error:
            print(f"{action} -> AUTH ERROR: {error}; no action taken")
            break
        except CLAIIMUnavailableError as error:
            print(f"{action} -> UNAVAILABLE: {error}; no action taken")
            break

11. 11

    Read the Chron record

    After the tests, wait for Chron processing and verify both attributed gate decisions.

    • 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 an application audit record. Privileged database access can change stored records; independent cryptographic verification remains a separate acceptance gate.

After onboarding

• Add agents within your licence limits. A licence permitting additional AI Orgs is required before creating child organisations for other teams.
• 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). Decommissioning preserves existing Chron records, subject to your deployment retention and backup configuration.

Common issues