​
What is an Instance?

An instance is your isolated Docker container running an AI agent framework (typically OpenClaw). Each instance:
  • Runs in its own network namespace
  • Has dedicated compute resources
  • Stores encrypted API keys in memory
  • Cannot access other users’ data
  • Has a unique port assignment (18000-19000 range)
Think of an instance as your personal AI agent server that only you control.

​
Instance Lifecycle

​
Create an Instance

​
Prerequisites

Before creating an instance, ensure:
  • Active subscription (any tier)
  • Within your tier’s instance limit
  • Valid JWT token

​
API Request

curl -X POST https://api.agentik.dev/api/instance/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-agent",
    "framework": "openclaw",
    "version": "latest"
  }'

​
Response

{
  "instance_id": "inst_7xKXtg2CW87",
  "name": "my-agent",
  "status": "provisioning",
  "framework": "openclaw",
  "port": 18042,
  "created_at": "2026-02-12T10:30:00Z",
  "estimated_ready": "2026-02-12T10:30:30Z"
}
Provisioning typically takes 10-30 seconds. Poll /api/instance/status to check progress.

​
Instance Provisioning Process

Backend provisions instances using dockerode (Docker SDK): 
async function provisionInstance(userId: string, config: InstanceConfig) {
  // 1. Allocate port from available range
  const port = await allocatePort(18000, 19000);
  
  // 2. Create Docker container
  const container = await docker.createContainer({
    Image: 'agentik/openclaw:latest',
    name: `agent-${userId}-${Date.now()}`,
    ExposedPorts: { '3000/tcp': {} },
    HostConfig: {
      PortBindings: {
        '3000/tcp': [{ HostPort: port.toString() }]
      },
      Memory: tierLimits[user.tier].memory,
      CpuShares: tierLimits[user.tier].cpu,
      NetworkMode: 'agentik_network',
    },
    Env: [
      `INSTANCE_ID=${instanceId}`,
      `USER_ID=${userId}`,
      `ENCRYPTION_KEY=${encryptionKey}`,
    ],
  });
  
  // 3. Start container
  await container.start();
  
  // 4. Record in database
  await db.query(
    `INSERT INTO docker_instances (id, user_id, container_id, port, status)
     VALUES ($1, $2, $3, $4, 'running')`,
    [instanceId, userId, container.id, port]
  );
  
  return { instanceId, port };
}
Backend uses dockerode SDK exclusively. Never shell out to docker commands (prevents injection attacks).

​
Check Instance Status

​
Poll for Ready State

async function waitForInstance(instanceId: string) {
  let attempts = 0;
  const maxAttempts = 60; // 60 seconds max
  
  while (attempts < maxAttempts) {
    const response = await fetch(`/api/instance/status/${instanceId}`, {
      headers: { "Authorization": `Bearer ${token}` },
    });
    
    const { status } = await response.json();
    
    if (status === "running") {
      return true; // Ready!
    }
    
    if (status === "failed") {
      throw new Error("Instance provisioning failed");
    }
    
    await new Promise(resolve => setTimeout(resolve, 1000)); // Wait 1s
    attempts++;
  }
  
  throw new Error("Instance provisioning timeout");
}

​
Status Response

{
  "instance_id": "inst_7xKXtg2CW87",
  "name": "my-agent",
  "status": "running",
  "framework": "openclaw",
  "port": 18042,
  "url": "https://inst-7xKXtg2CW87.agentik.dev",
  "uptime": 3600,
  "cpu_usage": 12.5,
  "memory_usage": 256,
  "created_at": "2026-02-12T10:30:00Z",
  "last_activity": "2026-02-12T11:15:22Z"
}

​
Configure API Keys

Once instance is running, upload encrypted API keys: 
curl -X POST https://api.agentik.dev/api/keys/store \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "instance_id": "inst_7xKXtg2CW87",
    "keys": {
      "OPENAI_API_KEY": "sk-...",
      "ANTHROPIC_API_KEY": "sk-ant-..."
    }
  }'

​
Encryption at Rest

Keys are encrypted using AES-256-GCM before storage: 
import crypto from 'crypto';

function encryptKey(plaintext: string, masterKey: string): string {
  const iv = crypto.randomBytes(12);
  const cipher = crypto.createCipheriv('aes-256-gcm', Buffer.from(masterKey, 'base64'), iv);
  
  let encrypted = cipher.update(plaintext, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  
  const authTag = cipher.getAuthTag().toString('hex');
  
  return JSON.stringify({
    encrypted,
    iv: iv.toString('hex'),
    authTag,
  });
}
Keys are decrypted only inside your instance, never in backend or frontend.

​
Access Your Instance

​
Direct Access

Each instance has a unique URL: 
https://inst-{instanceId}.agentik.dev
Example: 
https://inst-7xKXtg2CW87.agentik.dev

​
SSH/Terminal Access (Enterprise Only)

Enterprise tier users can SSH into instances: 
ssh -p 18042 agent@instance.agentik.dev

​
Manage Multiple Instances

​
List All Instances

curl https://api.agentik.dev/api/instance/list \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "instances": [
    {
      "instance_id": "inst_abc123",
      "name": "production-agent",
      "status": "running",
      "port": 18042,
      "created_at": "2026-02-10T08:00:00Z"
    },
    {
      "instance_id": "inst_def456",
      "name": "test-agent",
      "status": "stopped",
      "port": 18043,
      "created_at": "2026-02-11T14:30:00Z"
    }
  ],
  "limit": 5,
  "used": 2
}

​
Stop Instance

Temporarily stop an instance (preserves data): 
curl -X POST https://api.agentik.dev/api/instance/stop/inst_abc123 \
  -H "Authorization: Bearer $TOKEN"

​
Restart Instance

curl -X POST https://api.agentik.dev/api/instance/restart/inst_abc123 \
  -H "Authorization: Bearer $TOKEN"

​
Delete Instance

Permanently delete (cannot be undone): 
curl -X DELETE https://api.agentik.dev/api/instance/delete/inst_abc123 \
  -H "Authorization: Bearer $TOKEN"
Deleting an instance removes all data, logs, and configurations. This action cannot be undone.

​
Resource Limits by Tier

Free Tier

  • 1 instance max
  • 512 MB RAM
  • 1 CPU share
  • 100 MB storage

Pro Tier

  • 5 instances max
  • 1 GB RAM each
  • 2 CPU shares each
  • 1 GB storage each

Enterprise

  • Unlimited instances
  • 4 GB RAM each
  • 4 CPU shares each
  • 10 GB storage each

​
Monitoring & Logs

​
View Logs

curl https://api.agentik.dev/api/instance/logs/inst_abc123?tail=100 \
  -H "Authorization: Bearer $TOKEN"
Response: 
{
  "logs": [
    "[2026-02-12 10:30:15] Starting OpenClaw...",
    "[2026-02-12 10:30:16] API keys loaded (2 keys)",
    "[2026-02-12 10:30:17] Server listening on port 3000",
    "[2026-02-12 10:30:22] Received request: analyze transaction"
  ]
}

​
Metrics

Real-time metrics available at: 
GET /api/instance/metrics/inst_abc123
Returns CPU, memory, network, and request count.

​
Troubleshooting

  • Wait up to 60 seconds for initial provisioning
  • Check /api/instance/logs for error messages
  • If stuck >2 minutes, delete and recreate
  • Check subscription is active
  • Verify tier limits not exceeded
  • Ensure Docker daemon is healthy (backend issue)
  • Contact support with instance ID
  • Wait 30 seconds for DNS propagation
  • Verify instance status is “running”
  • Check firewall/network restrictions
  • Try direct port access: https://api.agentik.dev:18042
  • Verify keys were encrypted and stored successfully
  • Check instance logs for decryption errors
  • Re-upload keys via /api/keys/store

​
Next Steps

Key Management

Learn advanced API key management and rotation strategies