External Runtime Packages

External runtime packages are the customer-installable software that lets an approved external agent connect to IntuitivePM from a workstation, server, container platform, Kubernetes cluster, or automation tool.

The package is intentionally small. It contains the runtime manager, runtime bridge, adapter code, examples, and templates needed to connect a customer-approved runtime to IntuitivePM. It does not contain customer secrets, model provider keys, task data, or company data.

Recommended Delivery Model

IntuitivePM external runtimes should be delivered as versioned artifacts that customers can verify and operate independently.

For Enterprise production use, prefer either:

• a versioned bundle downloaded from IntuitivePM or supplied by IntuitivePM support, or
• a signed container image supplied by IntuitivePM.

What A Runtime Package Contains

A standard runtime package includes:

scripts/intuitivepm-agent-runtime.ts
scripts/external-agent-runtime.ts
scripts/agent-runtime/adapter.ts
scripts/external-agent-runtime.env.example
scripts/external-agent-runtime.manifest.example.json
README.md
CHANGELOG.md
checksums.txt

The runtime manager installs or updates the local runtime files and creates the supervised service definition for the selected instance.

The runtime bridge connects to IntuitivePM, exchanges credentials for short-lived tokens, receives wake-up events, fetches assigned work, heartbeats leases, reports progress, and calls the Agent API.

The executor adapter is optional. It connects the bridge to an approved local tool such as Claude Code, Codex, n8n, a container worker, or an internal automation runner.

Obtain The Package

Use the package source approved by your company administrator.

Recommended sources, in order:

1. System -> Integrations -> Agent Registry: copy the generated setup command for the approved runtime.
2. Agent Registry package download: download the versioned runtime bundle for offline review or controlled installation when your workspace exposes package downloads.
3. IntuitivePM support: request the current runtime bundle or container image for locked-down environments.

Avoid copying runtime files from chat transcripts, tickets, screenshots, or unreviewed file shares.

Verify The Package

Before installing a package on a production runtime host:

1. Confirm the package version matches your intended rollout.
2. Verify the checksum from checksums.txt.
3. Inspect the included README.md and CHANGELOG.md.
4. Confirm the package does not contain secrets.
5. Confirm your security team approves the runtime host, outbound destinations, and execution policy.

Example checksum check:

sha256sum -c checksums.txt

Install On Ubuntu With Systemd

Install the package with an instance name that identifies the runtime purpose.

Examples:

bun scripts/intuitivepm-agent-runtime.ts install codex-orchestrator
bun scripts/intuitivepm-agent-runtime.ts install claude-code-agent

Then configure the instance with the client ID, runtime ID, runtime label, and client secret from Agent Registry:

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 codex-orchestrator \
  --client-id <client-id> \
  --runtime-id <runtime-id> \
  --runtime-label "Ubuntu Codex Orchestrator" \
  --executor-enabled false

unset IPM_AGENT_CLIENT_SECRET

Validate and enable:

bun scripts/intuitivepm-agent-runtime.ts validate codex-orchestrator
bun scripts/intuitivepm-agent-runtime.ts enable codex-orchestrator
bun scripts/intuitivepm-agent-runtime.ts logs codex-orchestrator --follow

For a service that should survive logout or reboot, enable user lingering for the Linux service account:

sudo loginctl enable-linger <linux-user>

Install An Executor-Capable Runtime

Execution agents that run tools such as Claude Code should use a reviewed workspace and start in smoke mode.

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 claude-code-agent \
  --client-id <client-id> \
  --runtime-id <runtime-id> \
  --runtime-label "Ubuntu Claude Code Agent" \
  --executor-enabled true \
  --executor-workspace-root "$HOME/intuitivepm-agent-workspaces/claude-code-agent" \
  --smoke-mode true

unset IPM_AGENT_CLIENT_SECRET

Smoke mode validates IntuitivePM connectivity, comments, progress, leases, completion, and Review handoff without invoking the executor against real files.

Disable smoke mode only after the workspace, command, permission model, and company policy are approved:

bun scripts/intuitivepm-agent-runtime.ts configure claude-code-agent --smoke-mode false

Container And Kubernetes Delivery

For Docker or Kubernetes, use the approved IntuitivePM runtime image when available. Inject these values with your platform secret mechanism:

IPM_API_BASE=https://api.intuitivepm.net
IPM_AGENT_CLIENT_ID=<client-id>
IPM_AGENT_CLIENT_SECRET=<secret-from-secret-manager>
IPM_AGENT_RUNTIME_ID=<runtime-id>
IPM_AGENT_RUNTIME_LABEL=<runtime-label>
IPM_AGENT_EXECUTOR_ENABLED=<true-or-false>
IPM_AGENT_EXECUTOR_MANIFEST=<path-inside-container>

Platform teams should configure:

• restart policy
• CPU and memory limits
• read-only base filesystem where possible
• a writable approved workspace volume when execution is enabled
• secret injection from the platform secret store
• log collection
• outbound-only network policy to api.intuitivepm.net and approved supporting systems

Update And Rollback

Treat runtime packages like production software.

Recommended update process:

1. Review the runtime package release notes.
2. Test the new version on a non-production runtime or smoke task.
3. Stop the runtime service.
4. Install the new package version.
5. Run validate.
6. Start the service.
7. Confirm runtime.connected, runtime.ready:ack, pong, and the expected package version in logs.
8. Run a smoke task before assigning important work.

The runtime service runs from the installed package copy, not from a source checkout. Re-run the package install/upgrade command for each runtime instance after an IntuitivePM runtime package update, then restart the service. A connected runtime can still be outdated if the installed copy was not upgraded.

If the update fails, reinstall the previous approved package version and restart the service. The IntuitivePM task, lease, comment, and review state remains authoritative even if the local runtime is rolled back.

What Customers Should Not Do

Do not:

• run production agents from a manually kept-open terminal
• paste client secrets into chat, tickets, screenshots, or shell history
• reuse one credential across unrelated agents
• give execution agents orchestration review/control scopes unless explicitly approved
• run executor tools outside the approved workspace root
• run multiple live executor runtimes under the same OS user or home directory
• share Claude Code, Codex, or similar executor config/cache/session directories between runtime instances
• share a writable workspace between active runtimes without an approved locking and review design
• expose inbound firewall ports for normal runtimes
• treat local runtime logs as the official task record

Customer Setup Checklist

Before assigning real work:

1. Agent identity is approved in Agent Registry.
2. Runtime is registered, approved, and mapped to the intended Virtual Colleague.
3. Runtime package version is known and verified.
4. Runtime has a dedicated user, container, or pod with isolated home/config/cache/workspace/log paths.
5. Service is supervised by systemd, Docker, Kubernetes, n8n, or another approved manager.
6. Secret is stored in a protected environment file or secret manager.
7. Outbound HTTPS and WebSocket access to api.intuitivepm.net works.
8. Smoke task has passed.
9. Agent Activity shows the runtime online.
10. Review workflow has been tested.

Related Guides

• Connect External Agent Runtimes
• Run Codex And Claude Code As External Agents
• Agent Orchestration Architecture & Security
• Set Up Agent Orchestration