# Limitations of Terax AI: Step Counts, Security Sandboxes, and Context Constraints

> Discover Terax AI's limitations: 24 agent steps, restricted file access, and security sandbox constraints. Learn how these impact your AI agent's capabilities.

- Repository: [Crynta/terax-ai](https://github.com/crynta/terax-ai)
- Tags: deep-dive
- Published: 2026-07-06

---

**Terax AI enforces a hard limit of 24 agent steps per session, requires explicit user approval for any file-mutating operation, and runs inside a security sandbox that blocks arbitrary network requests and restricts filesystem access to the current workspace.**

Terax AI is an agent-driven development assistant from the `crynta/terax-ai` repository that balances autonomous capability with strict safety controls. Understanding the limitations of Terax AI is essential for designing prompts that complete within platform constraints and avoid unexpected session termination. These restrictions are intentionally hardcoded into the architecture to prevent infinite loops, unauthorized data exfiltration, and resource exhaustion.

## Hard Step Limits and Automatic Termination

The most significant constraint is the **24-step execution cap**. In `src/modules/ai/config.ts#L781`, the constant `MAX_AGENT_STEPS` is set to `24`, limiting how many tool calls a single agent session can issue.

This limit is enforced in the core run loop at `src/modules/ai/lib/agent.ts#L450` via the stop condition:

```typescript
stopWhen: stepCountIs(MAX_AGENT_STEPS)

```

Once the agent reaches this threshold, the stream terminates immediately, even if the task is incomplete. Complex workflows must be decomposed into smaller sub-agents or executed in *plan mode* to stay under this ceiling.

## Context Window and Token Management

Terax AI respects model-specific **token caps** defined in the model registry within [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts). When cumulative conversation tokens exceed the model’s context window, the system prunes older messages—specifically reasoning content—to preserve the most recent context.

This pruning caps how much historical context the model can reference in a single run, effectively limiting long conversational threads or large code-base analyses that exceed the underlying LLM’s memory.

## Security Sandbox and Approval Workflows

### Tool-Approval Gating for Mutating Operations

Any operation that modifies files or executes commands requires explicit user consent. In [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts), mutating tools are explicitly flagged with `needsApproval: true` (as noted in the AI subsystem documentation). The AI SDK pauses execution and presents an approval card in the UI, preventing silent side-effects until the user confirms the action.

### Filesystem and Network Restrictions

Terax AI operates within a **security deny-list** detailed in [`docs/architecture/security-model.md`](https://github.com/crynta/terax-ai/blob/main/docs/architecture/security-model.md). This sandbox:

- Blocks outbound network connections to prevent SSRF attacks
- Restricts filesystem read/write access to the current workspace only
- Prevents access to arbitrary system paths or sensitive OS directories

### Key Storage Protections

API keys **never touch the disk**. According to the README and implemented in [`src/modules/ai/lib/keyring.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/lib/keyring.ts), credentials are stored exclusively in the OS keychain via the `keyring` integration. The AI agent has no filesystem access to these secrets, eliminating leakage risks through tool calls or log files.

## Provider and Infrastructure Constraints

**Provider-specific limitations** vary by cloud backend. The provider registry in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts) defines available models, each with distinct rate limits, cost models, and token ceilings. Switching providers may change which features are available or how quickly quotas are consumed.

**Local-only inference** requires an OpenAI-compatible HTTP endpoint. The `buildLanguageModel` function uses `createOpenAICompatible` to wrap local models (e.g., Ollama). If the local model does not expose a spec-compliant API at an accessible URL, the AI side-panel cannot establish communication.

## Sub-Agent Recursion Guards

Terax AI prevents infinite agent nesting through a **recursion guard** defined in [`src/modules/ai/agents/registry.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/agents/registry.ts). Sub-agents are forbidden from calling `run_subagent` again; each sub-agent receives a fixed, whitelisted toolset that excludes recursive spawning. This design ensures that nested operations terminate predictably without stack overflow or resource exhaustion.

## UI Latency and Real-Time Constraints

The **Live Context Bridge** implementation in [`App.tsx`](https://github.com/crynta/terax-ai/blob/main/App.tsx) (referenced in AI subsystem documentation) introduces latency between the agent and the interface. The UI updates only after each tool response is approved and applied, creating a round-trip delay between the AI, the tool executor, and the renderer. Consequently, Terax AI does not support high-frequency, real-time interactive loops that require millisecond-level feedback.

## Working with Terax AI Limits in Code

### Checking the Step Limit Programmatically

```typescript
import { MAX_AGENT_STEPS } from './src/modules/ai/config';

// Verify the maximum agent steps allowed
console.log('Terax AI step limit:', MAX_AGENT_STEPS); // → 24

```

*Source:* `src/modules/ai/config.ts#L781`

### Handling the Approval Flow for File Operations

```typescript
import { runAgentStream } from './src/modules/ai/lib/agent';

const prompt = `
Please create a file called "hello.txt" with the contents:
Hello, Terax!
`;

runAgentStream(prompt).then(result => {
  // Execution pauses here until the user approves via the UI card
  console.log('Agent finished:', result);
});

```

The `write_file` tool triggers the approval workflow defined in [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts).

### Accessing Live Terminal Context

```typescript
import { getLive } from './src/App';

const cwd = await getLive('getCwd');
console.log('Current terminal directory:', cwd);

```

*Source:* [`App.tsx`](https://github.com/crynta/terax-ai/blob/main/App.tsx) wiring (AI subsystem docs line 83)

## Summary

- **Execution is capped at 24 steps** (`MAX_AGENT_STEPS` in [`src/modules/ai/config.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/config.ts)), after which the agent terminates automatically.
- **Mutating tools require explicit UI approval**, enforced by `needsApproval: true` flags in [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts).
- **Context windows are model-specific**, with automatic pruning of older messages when token limits are exceeded.
- **Security sandboxing** blocks arbitrary network requests and restricts filesystem access to the current workspace only.
- **API keys are volatized** in the OS keychain and never written to disk.
- **Sub-agents cannot recurse**; they operate with restricted toolsets to prevent infinite nesting.
- **Local models** must expose an OpenAI-compatible HTTP endpoint to function with the `createOpenAICompatible` wrapper.

## Frequently Asked Questions

### What happens when Terax AI reaches the 24-step limit?

The agent stream stops immediately via the `stopWhen: stepCountIs(MAX_AGENT_STEPS)` condition in `src/modules/ai/lib/agent.ts#L450`, regardless of task completion status. You must restart the session or break complex tasks into smaller sub-agents to continue work.

### Why does Terax AI require approval for file operations?

Mutating tools in [`src/modules/ai/tools/tools.ts`](https://github.com/crynta/terax-ai/blob/main/src/modules/ai/tools/tools.ts) are marked with `needsApproval: true` to prevent unauthorized modifications. This **tool-approval gating** ensures the AI cannot silently write, edit, or delete files without explicit user confirmation through the UI.

### Can Terax AI access files outside my project directory?

No. The security deny-list defined in [`docs/architecture/security-model.md`](https://github.com/crynta/terax-ai/blob/main/docs/architecture/security-model.md) restricts filesystem access to the current workspace. The agent cannot read or write paths outside the project root, protecting against path traversal attacks and unauthorized data access.

### How do I run Terax AI with a local model like Ollama?

You must expose an **OpenAI-compatible HTTP endpoint** on your local machine. Terax AI uses `buildLanguageModel` with `createOpenAICompatible` to communicate with local inference servers. If your local model does not match the OpenAI API schema, the AI side-panel cannot establish a connection.