# Security Considerations for Running Prime Agent with IPython: A Complete Guide

> Running Prime Agent with IPython requires careful security considerations. Understand the risks of this model-facing control environment and secure your system.

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

---

**Prime Agent executes model-generated Python code in a persistent IPython kernel that runs with full OS permissions, making it a model-facing control environment rather than a security sandbox.**

Prime Agent uses a persistent IPython kernel as its core execution engine, enabling powerful, stateful interactions between the agent and generated code. However, this design carries significant security implications that operators must understand before deploying in production. This article examines the security considerations for running Prime Agent with IPython, based on the architecture and runtime implementation in the `PrimeIntellect-ai/prime-agent` repository.

## Understanding the IPython Kernel Execution Model

The IPython kernel in Prime Agent is not sandboxed. It operates as a **model-facing control environment** where generated code runs with the same privileges as the Prime Agent worker process.

### Full OS Permissions Apply

In [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) (lines 47-51), the documentation explicitly states that kernel-side requests are authoritative. This means:

- File system operations access the same files as the host user
- Network requests originate from the host machine
- Subprocess calls execute with the worker's privileges

The kernel persists across turns and even session restores, as documented in [`packages/coding-agent/docs/rlm-runtime.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rlm-runtime.md) (lines 69-71). Variables, imports, and defined functions accumulate over the lifetime of a session, creating extended attack surfaces for any compromised or malicious code.

### Isolation Is for Stability, Not Security

The Prime Agent architecture isolates workers and kernels for **lifecycle and failure containment**, not security boundaries. Per [`packages/coding-agent/docs/rlm-runtime.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rlm-runtime.md) (lines 49-52), a kernel crash will not bring down the supervisor process, but this isolation does not prevent malicious code from reading sensitive files or exfiltrating data.

## Credential Exposure Risks

API keys and secrets enter the kernel through environment variables or the `!security` helper, as shown in [`packages/coding-agent/docs/providers.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/providers.md) (line 108). Because the kernel executes arbitrary Python, a compromised model or malicious skill code can:

- Inspect `os.environ` to extract secrets
- Read files containing credentials
- Make outbound network requests to exfiltrate data

```python

# Example: requesting a security review before executing sensitive code

await rlm(
    "Review this code for unsafe file system access and possible credential leaks",
    name="security-reviewer"
)

```

The `rlm()` call with `name="security-reviewer"` spawns a sub-agent that performs static analysis before execution. This audit workflow provides defense-in-depth but should not replace proper isolation.

## Trust Model and Skill Vetting

Prime Agent assumes that all Python-backed skills, extensions, and generated code are **trusted**. The [`packages/coding-agent/docs/rlm.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rlm.md) documentation (lines 41-44) warns that untrusted repositories require external sandboxing.

Skills install into the persistent kernel and remain available across sessions. Review skill code carefully before installation, following the guidelines in [`packages/coding-agent/skills/skill-creator/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/README.md).

## Mitigation Strategies for Safe Deployment

Effective security requires layering multiple controls around the IPython kernel.

### 1. Run Prime Agent in an External Sandbox

Containerize the entire Prime Agent process to limit kernel permissions independent of the host user:

```bash
docker run --rm -it \
  -v "$(pwd)":/workspace \
  -e PRIME_AGENT_KERNEL_VENV=/workspace/.venv \
  primeagent:latest \
  prime-agent

```

Docker, Podman, or `nsjail` all provide stronger isolation than Prime Agent's internal architecture.

### 2. Isolate the Kernel Virtual Environment

Use a dedicated virtual environment for the IPython kernel to prevent package conflicts and limit secret exposure:

```typescript
// Launch Prime Agent with custom isolated kernel venv
import { spawn } from "child_process";

const proc = spawn("prime-agent", [], {
  env: {
    ...process.env,
    PRIME_AGENT_KERNEL_VENV: "/tmp/prime-agent-kernel-venv",
  },
  stdio: "inherit",
});

proc.on("exit", (code) => {
  console.log(`Prime Agent exited with code ${code}`);
});

```

Avoid mounting directories containing sensitive configuration files. Store persistent session artifacts in paths with restricted permissions and verify directory ACLs on the `.prime/agent/` snapshot location.

### 3. Enforce Resource Limits

Configure the daemon's resource constraints to prevent denial-of-service attacks:

| Environment Variable | Purpose |
|----------------------|---------|
| `PRIME_AGENT_MAX_CONCURRENT_KERNEL_BOOTS` | Limits parallel kernel initialization |
| Daemon CPU/memory limits | Caps resource consumption per kernel |

### 4. Audit Generated Code Proactively

Enable automated review workflows for high-risk operations. The security reviewer pattern provides static analysis without requiring manual intervention:

```python

# Proactive review before file writes or network calls

await rlm(
    "Review this code for security issues",
    name="security-reviewer"
)

```

## Summary

- **The IPython kernel is not a sandbox** — it executes code with full host user permissions per [`architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/architecture.md)
- **Isolation targets stability, not security** — crashes are contained, but malicious actions are not blocked per [`rlm-runtime.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/rlm-runtime.md)
- **Credentials are vulnerable** — API keys injected via environment variables are accessible to any kernel code per [`providers.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/providers.md)
- **State persists across sessions** — variables and imports accumulate, extending attack surfaces over time
- **External sandboxing is essential** — Docker or equivalent containment provides the security boundary that Prime Agent lacks
- **Skill vetting is mandatory** — only install Python-backed skills from trusted sources following [`skill-creator/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/skill-creator/README.md) guidelines

## Frequently Asked Questions

### Does Prime Agent's IPython kernel run in a sandbox by default?

No. The IPython kernel executes with the same operating system permissions as the Prime Agent worker process. The documentation in [`packages/coding-agent/docs/architecture.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/architecture.md) explicitly describes the kernel as a "model-facing control environment" where generated code has authoritative access to host resources. Isolation mechanisms in Prime Agent only prevent kernel crashes from affecting the supervisor process, not malicious code from accessing files or networks.

### How can I prevent model-generated code from stealing my API keys?

Strip sensitive environment variables from the kernel's environment or run Prime Agent inside an external sandbox. API keys reach the kernel through `process.env` or the `!security` helper, making them visible to any executed Python code. Use `PRIME_AGENT_KERNEL_VENV` to isolate the Python environment and avoid mounting credentials directories into containers.

### What happens to kernel state when Prime Agent restarts?

The kernel's state persists across session restores, including variables, imports, and defined functions. Per [`packages/coding-agent/docs/rlm-runtime.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/docs/rlm-runtime.md) (lines 69-71), this persistence enables long-running workflows but also means that any malicious code or compromised state survives until explicitly cleared. Review kernel history after sessions involving untrusted code.

### Is it safe to install third-party skills from external repositories?

Only install skills after code review. Prime Agent's trust model assumes all Python-backed skills are trusted, and skills install into the persistent kernel where they remain available indefinitely. Follow the vetting guidelines in [`packages/coding-agent/skills/skill-creator/README.md`](https://github.com/PrimeIntellect-ai/prime-agent/blob/main/packages/coding-agent/skills/skill-creator/README.md) and sandbox Prime Agent when testing unfamiliar skills.