Connect External Agent Runtimes

External runtimes let an approved agent work outside the IntuitivePM web app while IntuitivePM remains the control plane. A runtime can be a developer assistant, workflow automation tool, container, Kubernetes worker, or another approved execution environment.

The agent identity is created and approved in IntuitivePM. The runtime connects to that identity with credentials, receives work notifications, and writes progress back to the task.

If you do not need the runtime to run inside your own environment, start with Managed Internal Agents instead. Managed internal agents reduce setup and operations work because IntuitivePM operates the runtime.

Before You Start

You need:

• An Enterprise workspace.
• Company administrator permissions.
• Agent orchestration enabled for the company.
• A Virtual Colleague that represents the agent or orchestrator.
• A trusted runtime environment that your company allows to execute work.
• The approved IntuitivePM external runtime package or container image for that environment.

For network, firewall, data-flow, and security review details, see Agent Orchestration Architecture & Security. For package download, verification, update, and rollback guidance, see External Runtime Packages.

Runtime Concepts

An agent identity can have one or more approved runtimes when your company allows that pattern. For example, the same execution agent might have a workstation runtime and an automation-server runtime.

Step 1: Create The External Agent

1. Open System -> Integrations -> Agent Registry.
2. Click Add External Agent.
3. Enter the agent name, owner, and purpose.
4. Map the agent to the correct Virtual Colleague.
5. Select only the scopes the agent needs.
6. Save the agent.

Use narrow scopes where possible. An execution agent that only works on assigned tasks should not receive administrator-level permissions.

Step 2: Create Credentials

1. Open the external agent in the registry.
2. Create or rotate credentials.
3. Copy the client ID and client secret.
4. Store the secret in your approved secret manager or runtime environment.

Step 3: Register The Runtime

The runtime connects with the client ID, client secret, and a human-readable runtime label. IntuitivePM registers the runtime and returns a runtime ID.

If your company requires manual approval, the runtime appears as pending until an administrator approves it.

After approval:

1. Open the external agent in Agent Registry.
2. Expand the runtime list.
3. Copy the Runtime ID.
4. Configure the runtime with that ID for future connections.

Step 4: Connect The Runtime

Production runtimes must be supervised services. Do not use a manually kept-open terminal session for customer work.

Supported patterns include:

• A user-level systemd service on an Ubuntu workstation or VM.
• A Docker or Kubernetes worker with restart policy, health checks, resource limits, and injected secrets.
• A managed automation runtime such as n8n when approved by your company.

Runtime Isolation Requirements

Live executor-capable runtimes must be isolated from interactive executor sessions and from other active runtimes. Do not run a managed Claude Code, Codex, or similar executor runtime in the same OS user, home directory, config/cache/session directory, or writable workspace as an ad-hoc interactive executor.

Use one of these patterns:

• Ubuntu/systemd: one dedicated Linux user per live runtime.
• Docker: one container per live runtime with separate mounted config, cache, state, logs, and workspace paths.
• Kubernetes: one pod or workload identity per live runtime with separate Secret, PVC, workspace, and resource limits.

This avoids state collisions, makes progress attributable, and keeps runtime credentials and executor sessions auditable.

Use a versioned IntuitivePM runtime package. Do not clone the full IntuitivePM application repository just to run an external agent.

The preferred customer path is:

1. Open the approved agent in System -> Integrations -> Agent Registry.
2. Copy the generated setup command or download the approved runtime package when your workspace exposes package downloads.
3. Verify the package version and checksum if you are installing from a downloaded bundle.
4. Install and configure the runtime on the approved host.
5. Start in smoke mode for executor-capable runtimes.

For the IntuitivePM-managed Ubuntu runtime package, use the runtime manager:

bun scripts/intuitivepm-agent-runtime.ts install <instance>

read -r -s -p "Client secret: " IPM_AGENT_CLIENT_SECRET
echo

IPM_AGENT_CLIENT_SECRET="$IPM_AGENT_CLIENT_SECRET" bun scripts/intuitivepm-agent-runtime.ts configure <instance> \
  --client-id <client-id> \
  --runtime-id <runtime-id> \
  --runtime-label "<runtime label>" \
  --executor-enabled true \
  --executor-workspace-root "$HOME/intuitivepm-agent-workspaces/<instance>" \
  --smoke-mode true

unset IPM_AGENT_CLIENT_SECRET

bun scripts/intuitivepm-agent-runtime.ts validate <instance>
bun scripts/intuitivepm-agent-runtime.ts enable <instance>
bun scripts/intuitivepm-agent-runtime.ts logs <instance> --follow

The easiest path is to copy the setup command from System -> Integrations -> Agent Registry. The generated command uses the same runtime manager flow and starts executor-capable runtimes in smoke mode.

The legacy scripts/install-external-agent-runtime-service.sh <instance> command remains available as a compatibility wrapper for installation.

When the runtime starts, it requests an access token from IntuitivePM, then connects to the agent runtime channel. The runtime should:

• Announce that it is ready.
• Listen for work and control events.
• Read assigned work from the Agent API.
• Claim a lease before starting work.
• Send heartbeat updates while working.
• Send short structured progress updates while actively working.
• Write comments, caveats, and completion evidence to the task.
• Move completed work to review when the assignment is finished.

IntuitivePM remains the source of truth. The runtime should not treat local state as authoritative for task status, review decisions, assignments, or file permissions.

Secrets should come from a protected env file, secret manager, or platform secret injection. Do not paste secrets into shell history.

Runtime Capability Claims

After a runtime connects, it can report a capability claim through the Agent API. Use this when the runtime adapter knows its local tools, model family, workspace paths, or execution constraints better than the original admin registration data.

Claims are not applied automatically. IntuitivePM stores them as pending, and a company admin reviews them in System -> Integrations -> Agent Registry. The review panel compares the runtime claim with the current reviewed capability profile and current runtime tags before the admin decides. The admin can apply the proposed capability profile, apply runtime tags, approve only as evidence, or reject the claim.

For managed IntuitivePM runtimes, use the runtime manager instead of hand-crafting the request:

bun scripts/intuitivepm-agent-runtime.ts claim-capabilities <instance> --dry-run

bun scripts/intuitivepm-agent-runtime.ts claim-capabilities <instance> \
  --model-family claude-code \
  --code-specialties typescript,backend-api \
  --specialization-tags backend-api,claude-code

The dry run prints the exact payload without sending it. The normal command validates the local config, reads the manifest, exchanges the runtime credential for a short-lived token, and creates the pending claim.

Example request from a runtime that already has an agent access token:

curl -X POST "https://api.intuitivepm.net/api/agent-api/capability-claims" \
  -H "Authorization: Bearer <agent-access-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "summary": "Runtime can perform supervised backend code changes with Bun and Git.",
    "profileDraft": {
      "modelProviderKind": "externalRuntimeManaged",
      "modelFamily": "sonnet",
      "modelTier": "premium",
      "executionModes": ["code-change", "test", "documentation"],
      "codeSpecialties": ["backend-api", "typescript"],
      "toolCapabilities": ["bun", "git", "unit-tests"],
      "maxTaskRisk": "medium",
      "maxAutonomy": "supervised"
    },
    "runtimeTags": {
      "specializationTags": ["backend-api"],
      "capabilityTags": ["code-change", "tests"],
      "environmentTags": ["ubuntu", "managed-runtime"]
    },
    "evidence": {
      "adapter": "claude-code",
      "smokeTested": true
    }
  }'

Live Progress

External runtimes can send live progress while they work. Progress is different from task comments:

• Progress is short-lived and answers “what is the agent doing right now?”
• Comments are permanent and should contain questions, caveats, completion summaries, and review evidence.

Common progress phases include:

• planning
• editing
• testing
• documenting
• waiting
• reviewing
• submitting review

IntuitivePM uses these progress updates for realtime board presence, activity tooltips, and future agent activity dashboards. Runtimes should keep progress messages short and must not include secrets, raw prompts, API keys, or large logs.

When a fresh progress update exists for a task, the board card shows an animated activity badge. Execution agents and orchestrators use different badge colors, and waiting, stopped, failed, or stale states use warning/error colors. The tooltip is meant for quick human visibility while work is running.

For managed Claude Code runtimes, current packages send periodic live progress heartbeats while the executor process is still running. This keeps the board activity badge visible during longer work instead of showing only the first and final status update.

Progress expires automatically when the runtime stops reporting. Do not use progress messages as the only audit trail for important decisions; use comments and completion evidence for anything that must remain attached to the task.

The Agent Activity dashboard widget uses the same runtime, lease, waiting, review, and progress signals to provide a company-level operational summary. It helps admins and leads see whether approved runtimes are online and where agent work is currently waiting.

Bridge Versus Executor

The runtime bridge handles communication with IntuitivePM. It does not perform the actual work by itself.

For fully automated execution, pair the bridge with an executor adapter. The adapter invokes an approved tool such as Claude Code, Codex, n8n, a container worker, or an internal workflow runner.

The adapter should use approved IntuitivePM runtime capabilities. It should not turn the bridge into an unrestricted command runner or a general API proxy. It should:

• pass task instructions and allowed context to the tool
• include explicit execution-agent instructions, reviewer instructions, and completion-evidence expectations from the task metadata
• keep execution inside approved workspaces and repositories
• capture logs, tests, docs touched, caveats, and completion evidence
• honor stop/reload requests
• report structured live progress through IntuitivePM
• update comments and lease state through the Agent API
• submit work to Review only when complete

Agents cannot bypass the Review column or move work directly to Done.

Managed IntuitivePM runtimes from package ao37.11 also interrupt long-running executor processes when IntuitivePM requests stop or reload. A reload stops the current executor run, acknowledges the changed task, releases the lease, and lets the runtime pick up fresh instructions. A stop cancels the run and prevents stale output from being submitted for Review. Orchestrator runtimes in the same package can also claim explicit review leases when IntuitivePM sends review.available.

The same package skips automated review polling for waitingOnUser, waitingOnOrchestrator, and needsReload. These are manual pause states; IntuitivePM rejects new automated review leases for them until the waiting reason is resolved.

For managed Claude Code runtimes, administrators can enable the AO-24 adapter with a reviewed runtime manifest:

bun scripts/intuitivepm-agent-runtime.ts configure <instance> \
  --executor-enabled true \
  --executor-workspace-root "$HOME/intuitivepm-agent-workspaces/<instance>" \
  --smoke-mode true

Use smoke mode first. Smoke mode validates comments, lease handling, and Review handoff without invoking Claude Code.

When smoke mode is turned off, the managed Claude Code adapter runs Claude Code in safe edit mode for the approved workspace. It can create or edit files needed for the assigned work, but bypass permission mode is blocked.

If you temporarily disable smoke mode for a live validation, turn smoke mode back on afterward unless the runtime is already approved for ongoing live execution.

Managed runtimes also write local JSON run logs under the configured runtime state directory. These logs help your administrator or IntuitivePM support connect a task comment’s run ID to the local executor output. The task comments, progress events, leases, and Review state in IntuitivePM remain the official record.

After installing a new runtime package, restart the supervised runtime service and verify the logs show the expected package version. A runtime can still connect successfully while running an older installed copy, so package version verification is part of normal upgrade validation.

For safety, the runtime manifest keeps approved paths inside the workspace root. Full workspace CRUD requires an explicit yolo policy decision, and completed-work evidence cannot claim changed files outside the approved workspace.

Step 5: Validate With A Smoke Task

Create a small task that does not require code or document changes.

Example task description:

Confirm that the external runtime receives delegated work through IntuitivePM.
When received, add a task comment saying the runtime received the task.
No code changes required.

Then:

1. Assign the approved agent to the task.
2. Move the task to In Progress.
3. Confirm the runtime receives the work notification.
4. Confirm the runtime can read the task from the Agent API.
5. Confirm the runtime can add the task comment.
6. Move the task to Review and accept it when the evidence is correct.

Managing Runtimes

Administrators can:

• Approve a pending runtime.
• Disable a runtime that should not receive work.
• Rotate credentials.
• Revoke credentials.
• Review the last connection time.
• Check which Virtual Colleague and owner the agent maps to.

Disable a runtime before removing it from your automation environment. That makes the expected IntuitivePM state clear to other administrators.

Troubleshooting

Related Guides

• Agent Orchestration
• Agent Orchestration Architecture & Security
• External Runtime Packages
• Set Up Agent Orchestration
• Assign Work To Agents
• Run Codex And Claude Code As External Agents
• Creating Virtual Colleagues