# Prime Agent Trust Model for Programmatic IPython Tool Execution

> Explore Prime Agent's trust model for programmatic IPython tool execution. We isolate untrusted inputs with strict validation and credential isolation, ensuring a secure environment.

- Repository: [Prime Intellect/prime-agent](https://github.com/PrimeIntellect-ai/prime-agent)
- Tags: architecture
- Published: 2026-08-12

---

**Prime Agent's trust model treats the persistent IPython kernel as a trusted execution environment while isolating all external inputs as untrusted, with strict envelope validation and credential isolation.**

The **Prime Agent** open-source agent framework implements a multi-layered trust model for programmatic IPython tool execution through its **RLM (Runtime Language Model) programming model**. This design enables powerful code execution capabilities while maintaining security boundaries between trusted kernel operations and untrusted external data. Understanding this trust model is essential for developers building secure AI agents that execute arbitrary code.

## Kernel-Level Trust: The Persistent IPython Environment

Prime Agent launches an **IPython kernel once per session** that remains alive across conversation turns. This kernel constitutes a **trusted execution environment** owned entirely by the Prime Agent process.

All code executing inside the kernel—including Python cells, imported skills, and persistent variables—runs within this controlled process. **Critical security property**: the kernel's state is never serialized or transmitted over the network, preventing untrusted data from persisting in the execution environment.

The trust establishment occurs in [`packages/coding-agent/src/modes/interactive/interactive-mode.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/src/modes/interactive/interactive-mode.ts), where the session explicitly "trusts the live connection" to the kernel:

```typescript
// From interactive-mode.ts#L1693
// The session marks the kernel connection as trusted for the duration
// of the agent's lifecycle. No external process can inject state.

```

This architectural choice means that once the kernel is established, operations within it maintain trust continuity without requiring re-validation on every tool call.

## Tool-Call Envelope Validation

When the language model invokes Python execution, it does so through the built-in **IPython tool**. This tool call follows a strict envelope pattern that separates trusted kernel output from untrusted input vectors.

The **ACP (Agent-Controlled-Protocol) layer** enforces schema validation on tool outputs. Only fields defined by the tool schema—text output, images, and rich display data—are accepted; any additional payload is discarded. This prevents arbitrary data injection into the kernel environment.

The validation logic appears in `packages/coding-agent/src/modes/rpc/rpc-client.ts#L666`:

```typescript
// From rpc-client.ts#L666
// After the command executes, the response is cast to the expected
// tool output shape. Malformed responses are rejected at this boundary.

```

This schema-enforced validation effectively "trusts" only well-formed tool outputs that conform to the expected contract.

## Untrusted External Input Handling

Prime Agent applies a **default-deny posture** to all data originating outside the kernel. Raw shell commands, network replies, and user-provided code are treated as **untrusted** and require explicit markers or authorization.

### Shell Execution Requires Explicit Markers

Shell commands must use the `%%bash` magic marker, enforced by the framework:

```typescript
await tool.execute({
  title: "IPython cell",
  source: "%%bash\nls -l /tmp",
});
// The kernel parser validates the %%bash marker before shell execution.
// Commands without this marker are rejected for shell operations.

```

### Dependency Installation Requires User Authorization

The system refuses to install Python packages into the kernel without explicit user authorization, preventing supply-chain attacks through dependency injection.

### Socket Peer Filtering

In `packages/coding-agent/src/modes/daemon/daemon-protocol.ts#L184`, incoming messages from socket peers are re-filtered because the peer is explicitly **not trusted**:

```typescript
// From daemon-protocol.ts#L184
// Messages from the socket peer are untrusted and must be
// re-validated before entering the trusted kernel boundary.

```

## Credential Isolation and Ephemeral Injection

**Credentials never persist in the IPython environment**. API keys, OAuth tokens, and other secrets follow a strict fetch-and-inject pattern:

1. Credentials are retrieved from secure storage ([`env-api-keys.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/env-api-keys.ts))
2. They are substituted **only for the duration of the specific call**
3. The kernel never holds or "trusts" a persisted secret

This policy is enforced in `packages/coding-agent/src/core/mcp/mcp-manager.ts#L135`, where the comment explicitly states that **auth.json entries are not trusted for kernel use**:

```typescript
// From mcp-manager.ts#L135
// Auth credentials from auth.json are fetched per-use and never
// trusted as kernel-local state. Each injection is ephemeral.

```

## State Restoration with Process Verification

When sessions resume, the kernel may restore previous state. However, Prime Agent implements **verifiable state restoration** through a trusted marker protocol.

The restoration message is always prefixed with `◆ Restored IPython kernel state`, enabling the model to confirm that the kernel is the **same trusted process** it originally created. This marker prevents session hijacking or substitution attacks.

Tests in `packages/coding-agent/test/suite/regressions/4530-ipython-state-restore-message.test.ts#L115-L122` assert this security property:

```typescript
// State restoration verification pattern
if (output.startsWith("◆ Restored IPython kernel state")) {
  // Trust the restored state: signature matches original kernel
  proceedWithTrustedSession();
} else {
  // Potential substitution attack: reject restoration
  throw new SecurityError("Untrusted kernel state");
}

```

## Trust Model Implementation Files

| Component | File Path | Security Function |
|-----------|-----------|-------------------|
| Kernel trust establishment | `packages/coding-agent/src/modes/interactive/interactive-mode.ts#L1693` | Marks live kernel connection as trusted |
| Tool output validation | `packages/coding-agent/src/modes/rpc/rpc-client.ts#L666` | Schema-enforced envelope validation |
| Untrusted peer filtering | `packages/coding-agent/src/modes/daemon/daemon-protocol.ts#L184` | Re-filters socket messages |
| Credential isolation | `packages/coding-agent/src/core/mcp/mcp-manager.ts#L135` | Ephemeral credential injection |
| State restore verification | `packages/coding-agent/test/suite/regressions/4530-ipython-state-restore-message.test.ts#L115-L122` | Tests trusted restore marker |
| RLM design documentation | [`packages/coding-agent/docs/rlm.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rlm.md) | Authoritative trust model specification |

## Summary

Prime Agent's trust model for programmatic IPython tool execution implements defense in depth through five key mechanisms:

- **Kernel-level trust**: Single persistent process with no network serialization of state
- **Schema-enforced tool envelopes**: ACP validation rejects malformed outputs
- **Untrusted input isolation**: Default-deny posture for external data with explicit markers required
- **Credential ephemerality**: Secrets injected per-call, never persisted in kernel
- **Verifiable state restoration**: Cryptographic-style marker confirms process identity across sessions

This architecture enables powerful, stateful code execution while maintaining strict boundaries between trusted kernel operations and untrusted external inputs.

## Frequently Asked Questions

### How does Prime Agent prevent malicious code injection through tool outputs?

Prime Agent's **ACP layer validates tool outputs against strict schemas** in `rpc-client.ts#L666`. Only fields defined by the IPython tool schema—text, images, and display data—are accepted. Additional or malformed payload fields are discarded, preventing injection attacks through oversized or malicious tool responses.

### Can the IPython kernel be compromised by network-based attacks?

No. The kernel **never receives serialized state over the network**. It is launched locally by Prime Agent and maintains trust through its process identity. The session "trusts the live connection" as noted in `interactive-mode.ts#L1693`, meaning network intermediaries cannot influence kernel state without breaking the local process boundary.

### What happens if user-provided code attempts to access shell or install packages?

Untrusted user code receives **default-deny enforcement**. Shell commands require the explicit `%%bash` marker, which the kernel parser validates. Package installation requires explicit user authorization through the framework's permission system. These constraints are implemented in the kernel's cell processing pipeline before execution occurs.

### How does state restoration maintain security across session resumptions?

Restored states carry a **verifiable marker** (`◆ Restored IPython kernel state`) that confirms the kernel's process identity. Tests in [`4530-ipython-state-restore-message.test.ts`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/4530-ipython-state-restore-message.test.ts) enforce this marker's presence. Without this marker, the framework treats the restored state as potentially substituted and rejects the session continuation.