Quickstart Guide

Get Identity OS running in 5 minutes.

Prerequisites

• Python 3.8+ (or Node.js 16+ for TypeScript)
• pip or npm
• Basic understanding of AI agents

Installation

Option 1: Install via pip (Recommended)

pip install identity-os-sdk

Then set your API key:

export IDENTITY_OS_API_KEY="idos_sk_your_key_here"

Get an API key by:

1. Visit identity-os.dev
2. Sign up or log in
3. Go to Settings → API Keys
4. Create a new key
5. Copy it (it's shown only once)

Option 2: Run Locally with Docker

# Contact xiocasso@outlook.com for self-hosted access
docker compose up

This starts: - Identity OS API on http://localhost:8000 - PostgreSQL database - Redis cache

The local API has no authentication. Use http://localhost:8000 as your base URL.

Option 3: Install TypeScript SDK

npm install @identity-os/sdk

Create Your First Instance

An instance is a stateful personality model for one agent. Create it once, then feed observations to it over time.

PythonTypeScript

from identity_os_sdk import IdentityOS

# Initialize client
client = IdentityOS(api_key="idos_sk_xxx")
# Or locally: client = IdentityOS(base_url="http://localhost:8000")

# Create an instance for your agent
instance = client.instances.create(
    name="Aria",
    description="Helpful research assistant"
)

print(f"Instance created: {instance.id}")
# Output: inst_9f190826e20c49ea

import { IdentityOS } from "@identity-os/sdk";

const client = new IdentityOS({
  apiKey: "idos_sk_xxx"
  // Or locally: baseUrl: "http://localhost:8000"
});

// Create an instance
const instance = await client.instances.create({
  name: "Aria",
  description: "Helpful research assistant"
});

console.log(`Instance created: ${instance.id}`);
// Output: inst_9f190826e20c49ea

You now have a stateful personality model.

Every observation you send updates its state. The state is persisted automatically.

Process Your First Observation

Observations are behavioral signals. They tell Identity OS: "My agent is in [mode], with signal strength [0-1]."

The 7 modes are:

• Perception — gathering info, cautious
• Exploration — testing boundaries, curious
• Order — following structure, disciplined
• Assertion — confident action, bold
• Connection — collaborative, empathetic
• Identity — self-consistent, principled
• Stress Response — under pressure, simplifying

PythonTypeScript

from identity_os_sdk import Mode

# Agent is exploring a new tool
result = client.engine.process(
    instance_id=instance.id,
    mode_target=Mode.EXPLORATION,
    signal_strength=0.8,     # Strong signal
    confidence=0.9           # High confidence in this reading
)

print(f"Mode strengths: {result.snapshot.mode_strengths}")
print(f"Stress state: {result.snapshot.stress_state}")
print(f"Energy level: {result.snapshot.energy_level}")

import { Mode } from "@identity-os/sdk";

const result = await client.engine.process(instance.id, {
  modeTarget: Mode.EXPLORATION,
  signalStrength: 0.8,
  confidence: 0.9
});

console.log(`Mode strengths:`, result.snapshot.modeStrengths);
console.log(`Stress state:`, result.snapshot.stressState);
console.log(`Energy level:`, result.snapshot.energyLevel);

Each call returns:

• snapshot — Current identity state (all modes, energy, stress)
• contract — ExecutionContract (what agent can/can't do)
• drift — Drift detection status

Read the ExecutionContract

The ExecutionContract is what your agent actually uses. It tells you:

PythonTypeScript

contract = result.contract

print("Allowed actions:", contract.allowed_actions)
# Output: ['explore', 'question', 'pivot', 'suggest']

print("Forbidden actions:", contract.forbidden_actions)
# Output: ['emotional_manipulation', 'identity_override']

print("Decision style:", contract.decision_style)
# Output: {
#   'tempo': 'exploratory',
#   'risk': 'seeking',
#   'expressiveness': 'high',
#   'commitment_threshold': 'low'
# }

print("Energy level:", contract.energy_level)
# Output: 0.83

print("Stress state:", contract.stress_state)
# Output: 'LOW'

print("Dominant modes:", contract.dominant_modes)
# Output: ['Exploration', 'Assertion']

const contract = result.contract;

console.log("Allowed actions:", contract.allowedActions);
console.log("Decision style:", contract.decisionStyle);
console.log("Energy level:", contract.energyLevel);
console.log("Stress state:", contract.stressState);

Use this in your agent:

# Guard exploratory actions
if "explore" in contract.allowed_actions:
    # Try a novel approach
    response = agent.explore_new_tool()
else:
    # Stick with safe patterns
    response = agent.use_known_tool()

# Scale down when stressed
if contract.stress_state == "HIGH":
    # Only do essential work
    pass
elif contract.energy_level < 0.3:
    # Running low on energy budget
    pass
else:
    # Normal operations
    pass

5-Minute Tutorial: Multi-Turn Scenario

Here's a realistic flow — an agent researching a topic over multiple turns:

PythonTypeScript

from identity_os_sdk import IdentityOS, Mode

client = IdentityOS(api_key="idos_sk_xxx")
agent = client.instances.create(name="Researcher")

# Turn 1: Agent starts, perceiving the task
print("\n=== Turn 1: Initial Perception ===")
result = client.engine.process(
    instance_id=agent.id,
    mode_target=Mode.PERCEPTION,
    signal_strength=0.7,
    confidence=0.8,
    context={"task": "research climate change"}
)
print(f"Energy: {result.contract.energy_level}")
print(f"Allowed: {result.contract.allowed_actions[:3]}")

# Turn 2: Agent explores sources
print("\n=== Turn 2: Exploration ===")
result = client.engine.process(
    instance_id=agent.id,
    mode_target=Mode.EXPLORATION,
    signal_strength=0.85,
    confidence=0.75
)
print(f"Energy: {result.contract.energy_level}")
print(f"Tempo: {result.contract.decision_style['tempo']}")

# Turn 3: Agent hits a contradiction, stress rises
print("\n=== Turn 3: Contradictory Data (Stress Rising) ===")
result = client.engine.process(
    instance_id=agent.id,
    mode_target=Mode.STRESS_RESPONSE,
    signal_strength=0.6,
    confidence=0.95  # High confidence it IS stressed
)
print(f"Stress: {result.contract.stress_state}")
print(f"Allowed: {result.contract.allowed_actions}")
# Notice: fewer actions allowed, more conservative tempo

# Turn 4: Agent recovers, returns to order
print("\n=== Turn 4: Recovery ===")
result = client.engine.process(
    instance_id=agent.id,
    mode_target=Mode.ORDER,
    signal_strength=0.8,
    confidence=0.9
)
print(f"Stress: {result.contract.stress_state}")
print(f"Energy: {result.contract.energy_level}")
print(f"Dominant modes: {result.contract.dominant_modes}")

# Get final snapshot
snapshot = client.engine.get_snapshot(agent.id)
print(f"\n=== Final State ===")
print(f"Total cycles: {snapshot.cycle_count}")
print(f"Stability: {snapshot.stability_index}")

import { IdentityOS, Mode } from "@identity-os/sdk";

const client = new IdentityOS({ apiKey: "idos_sk_xxx" });
const agent = await client.instances.create({ name: "Researcher" });

// Turn 1: Initial perception
console.log("\n=== Turn 1: Perception ===");
let result = await client.engine.process(agent.id, {
  modeTarget: Mode.PERCEPTION,
  signalStrength: 0.7,
  confidence: 0.8,
  context: { task: "research climate change" }
});
console.log(`Energy: ${result.contract.energyLevel}`);

// Turn 2: Exploration
console.log("\n=== Turn 2: Exploration ===");
result = await client.engine.process(agent.id, {
  modeTarget: Mode.EXPLORATION,
  signalStrength: 0.85,
  confidence: 0.75
});
console.log(`Tempo: ${result.contract.decisionStyle.tempo}`);

// Turn 3: Stress
console.log("\n=== Turn 3: Stress ===");
result = await client.engine.process(agent.id, {
  modeTarget: Mode.STRESS_RESPONSE,
  signalStrength: 0.6,
  confidence: 0.95
});
console.log(`Stress: ${result.contract.stressState}`);

// Turn 4: Recovery
console.log("\n=== Turn 4: Recovery ===");
result = await client.engine.process(agent.id, {
  modeTarget: Mode.ORDER,
  signalStrength: 0.8,
  confidence: 0.9
});
console.log(`Final stress: ${result.contract.stressState}`);
console.log(`Dominant modes: ${result.contract.dominantModes}`);

What you should see:

• Turn 1–2: Energy depletes slowly, normal actions allowed
• Turn 3: Stress rises to HIGH or MED, energy drops faster, fewer actions allowed
• Turn 4: Stress recovers as Order mode activates, actions expand again

Next Steps

1. Understand the concepts — Read The 7 Modes to learn what each mode does
2. Learn stress & drift — See Stress Model and Drift Detection
3. Integrate with your framework — Check out LangGraph or CrewAI
4. Deep dive into the API — Visit API Reference

Common Patterns

Pattern 1: Guard a Risky Action

result = client.engine.process(instance_id, mode_target=Mode.ASSERTION)
contract = result.contract

if contract.stress_state in ["HIGH", "OVER"]:
    # Don't execute high-risk actions under stress
    return handle_safe_path()

if "execute" in contract.allowed_actions:
    return agent.execute_plan()
else:
    return agent.get_clarification()

Pattern 2: Adapt Decision Style

contract = result.contract
tempo = contract.decision_style["tempo"]

if tempo == "decisive":
    # Agent is confident, move fast
    return fast_path()
elif tempo == "exploratory":
    # Agent is curious, encourage novel ideas
    return exploratory_path()
else:
    # Agent is cautious, validate everything
    return validated_path()

Pattern 3: Monitor Energy

if contract.energy_level < 0.2:
    # Energy is depleted, simplify tasks
    return simplified_task_queue()
elif contract.energy_level < 0.5:
    # Energy is running low, be selective
    return priority_task_queue()
else:
    # Energy is good, full capability
    return full_task_queue()

Troubleshooting

I'm getting authentication errors

Check your API key:

echo $IDENTITY_OS_API_KEY

If empty, set it:

export IDENTITY_OS_API_KEY="idos_sk_your_key_here"

If you're running locally, use the Docker base URL instead:

client = IdentityOS(base_url="http://localhost:8000")

My instance isn't updating

Make sure you're passing instance_id correctly. Check the returned ID:

instance = client.instances.create(name="Test")
print(instance.id)  # Should start with "inst_"

I'm not seeing drift detected

Drift detection requires multiple turns with conflicting observations. See Drift Detection for details.

Energy is dropping too fast

Energy cost scales with active modes and stress level. See Stress Model for cost details.

Getting Help

• 📖 Docs — You're reading them!
• 🐙 GitHub Issues — github.com/identity-os/identity-os/issues
• 💬 Discord — discord.gg/identity-os
• 📧 Email — support@identity-os.dev