Documentation

Everything you need to provision, monitor, and respond to monkeys in production.

Quickstart

This guide walks you through provisioning your first monkey. Estimated time: under 5 minutes. Estimated time until first incident: shortly thereafter.

Prerequisites

The Monkey Manifest

Monkeys are declared using a YAML manifest. Submit it to the provisioning API or pipe it directly with curl.

yamlapiVersion: imo.online/v1
kind: Monkey
metadata:
  name: henry.kissinger
  namespace: satellite-of-love
spec:
  species: chimpanzee
  temperament: unpredictable
  bananaCredits: 500
  namedFor: scalp              # required field; value is cosmetic only
  postureThreshold: low        # how much ambient aggression henry.kissinger tolerates
  compatibleOperators:
    - crow.t.robot
    - tom.servo
  incompatibleOperators:
    - mike.nelson               # triggers escalation; see RB-047
⚠️
Posture Advisory Any operator not listed under compatibleOperators will be perceived as a threat. Do not assume aggressive posture near the delivery zone. If you are unsure what constitutes aggressive posture, it is probably whatever you are doing right now.

Provision via curl

bashcurl -X POST https://instantmonkeys.online/v1/monkeys/provision \
  -H "Authorization: Bearer $IMO_API_KEY" \
  -H "Content-Type: application/yaml" \
  --data-binary @monkey.yaml

Delivery & Webhooks

Upon successful delivery, IMO sends a monkey.delivered event to your configured webhook endpoint. Register your endpoint in the IMO dashboard under Settings → Webhooks.

Example payload:

json{
  "event": "monkey.delivered",
  "monkey_id": "henry.kissinger",
  "namespace": "satellite-of-love",
  "species": "chimpanzee",
  "crate_integrity": "nominal",
  "banana_credits_remaining": 500,
  "delivered_at": "1997-03-02T09:14:00Z",
  "warnings": [
    "Do not assume aggressive posture.",
    "Crate will be breached within 60 seconds of delivery. This is expected behavior."
  ]
}
ℹ️
Note on crate breach The crate breach event is informational only and does not indicate a delivery failure. A separate monkey.escaped webhook fires automatically. You do not need to handle this; it is too late.

API Reference

Base URL: https://instantmonkeys.online/v1

All requests require an Authorization: Bearer <token> header. Rate limits: 100 monkeys/hour on Pro, unlimited on Enterprise Ape.

Provision a monkey

POST /monkeys/provision

Provisions a new monkey from the global primate pool and initiates delivery to your registered environment.

FieldTypeDescription
name required string Hostname for the monkey. Must be DNS-compliant. We recommend henry.kissinger.
species string Primate species. Default: chimpanzee. See species catalog for available options.
bananaCredits integer Initial banana credit allocation. Insufficient credits are the leading cause of INC-class incidents.
incompatibleOperators string[] Operators whose posture will be interpreted as aggressive. Triggers monkey.hostile alert.

Get monkey details

GET /monkeys/{id}

Returns full configuration and current state for the specified monkey.

If the monkey's location is unknown, the location field will be null and fate will be "unknown". This is not an error condition. We have simply lost track of the monkey.

Get monkey status

GET /monkeys/{id}/status

Returns the current operational status of the specified monkey. Possible values: nominal, escaped, hostile, in_rafters, unconscious, unknown.

json{
  "monkey_id": "henry.kissinger",
  "status": "in_rafters",
  "threat_level": "HIGH",
  "last_seen": "2024-01-15T10:38:00Z",
  "objects_thrown": 14,
  "banana_credits_remaining": 0,
  "active_incident": "INC-0822",
  "recommended_action": "See IMO-RB-047"
}

Delete a monkey

DELETE /monkeys/{id}

Attempts to deprovision the specified monkey.

🚫
405 Method Not Allowed We do not accept returns. This endpoint will always return 405. This is by design. You accepted the terms at checkout.

Get banana credit balance

GET /bananas/credits

Returns the current banana credit balance for your account. Monitor this closely. Banana credit exhaustion is the leading precursor to monkey.hostile events and the number one cause of INC-class incidents in production environments.

json{
  "credits_remaining": 0,
  "credits_consumed_today": 500,
  "burn_rate": "critical",
  "estimated_time_to_incident": "imminent",
  "recommendation": "Top up immediately. Do not make eye contact."
}

IMO-RB-047: Rogue Primate Response

Runbook IDIMO-RB-047
SeverityP1 — Critical
Triggermonkey.hostile alert
Last updatedAfter INC-0822
OwnerOn-Call Engineering

Overview

This runbook covers the response procedure for a rogue or hostile primate deployment. It is most commonly triggered when a monkey perceives operator posture as aggressive. Follow steps in order. Do not skip steps. Step 3 is the one people always skip. Do not skip step 3.

🚨
Do not engage third-party primate whisperers Field data from INC-0822 confirms a 100% defection rate. Any external resource brought in to calm the monkey will join the monkey. Do not call Bobo.

Response Steps

1

Acknowledge the alert

Acknowledge monkey.hostile in your alerting platform. Update the incident channel. Set status to investigating.

2

Check banana credit balance

Call GET /v1/bananas/credits. If credits_remaining is 0, top up immediately via the IMO dashboard. Banana credit exhaustion is the root cause in approximately 80% of hostile incidents. Restoring credits may resolve the incident without further intervention.

3

Assess operator posture

Identify which operator is in proximity to the monkey. Verify their posture is not being interpreted as aggressive. If unsure, assume it is. Have the operator adopt a non-threatening posture immediately:

  • Rub chest using the back of the hand. The front of the hand will make things worse.
  • Loll head slowly side to side.
  • Drool slightly.
  • Produce soft "ook" vocalizations. Volume should be low. Do not maintain eye contact.

Continue until threat level decreases or monkey retreats to rafters. Retreating to rafters is an improvement. Update incident status to monitoring.

4

Rafter containment protocol

If the monkey has taken up residence in the rafters, maintain non-aggressive posture and do not attempt to retrieve them. Continue "ook" vocalizations. Monitor objects_thrown metric via GET /v1/monkeys/{id}/status. A decreasing throw rate indicates de-escalation. An increasing rate indicates escalation to step 5.

5

Escalate to P1 — do not call Bobo

If de-escalation attempts have failed and object-throwing continues at scale, escalate to P1. Page the on-call lead. Update incident severity to CRITICAL.

You may be tempted at this point to engage a third-party primate whisperer. Do not. See the warning at the top of this runbook. Bobo will defect. Bobo will throw microwaves.

6

Blowgun authorization

Blowgun use requires explicit approval from the on-call lead. Submit authorization request in the incident channel with the following information:

  • Monkey ID and current status
  • Confirmation that steps 1–5 were followed in order
  • Confirmation that Bobo was not contacted
  • Current objects_thrown count and most recent object class (e.g., microwave, chair, unspecified debris)

Upon approval, deploy blowgun. Both the monkey and any defected primate whisperers will fall unconscious. The immediate threat will be resolved.

⚠️
Post-resolution expectation management Bots and other non-human operators will express displeasure at the blowgun resolution regardless of outcome. This is expected and non-actionable. Update the incident to resolved and begin postmortem scheduling.
7

Post-incident

Confirm monkey location and current status via GET /v1/monkeys/{id}/status. If status returns "unknown" and "fate": "unknown", document this in the incident record and close. Fate unknown is an accepted terminal state. Do not reopen the incident to investigate fate.

Schedule a blameless postmortem within 48 hours. The postmortem template is available in the IMO dashboard under Runbooks → Templates → INC-Primate-Postmortem.