How Reasonix Injects OS and Shell Environment Summaries at Startup

Reasonix automatically builds a stable environment summary at startup by probing the host OS and shell, caching the results to disk, and injecting them as a TOML block into the model's system prompt.

The DeepSeek-Reasonix agent requires accurate host context to generate valid system commands and file paths. At every startup, the application executes a deterministic injection pipeline that detects the operating system, identifies the default shell, and captures a filtered snapshot of environment variables. This ensures the language model receives consistent, relevant context from the first interaction.

The Three-Stage Injection Pipeline

The injection process follows a structured pipeline implemented across three core components in the esengine/DeepSeek-Reasonix codebase.

Stage 1: Host Environment Probing

In internal/environment/probe.go, the Probe() function orchestrates data collection through lightweight detection routines. The function returns a ProbeResult struct containing the OS type, shell details, and filtered environment variables.

The detection logic handles platform-specific nuances. On Unix systems, it uses runtime.GOOS combined with uname -s for canonical OS naming, while on Windows it reads the registry for version information. For shell resolution, sandbox.ResolveShell (located in internal/sandbox/shell.go) examines the $SHELL environment variable (or %COMSPEC% on Windows), falls back to common defaults like /bin/bash or powershell.exe, and queries version strings using bash --version or pwsh -Version.

Stage 2: Configuration Rendering

The internal/config/render.go file contains renderEnvironmentConfig, which transforms the Environment struct into a formatted TOML block. This function is invoked by RenderTOML to produce the [environment] section that appears in the final configuration output.

Stage 3: Prompt Injection

Finally, internal/agent/prompt.go (called from cmd/reasonix/main.go) assembles the system prompt via BuildSystemPrompt. This function concatenates the user-defined system prompt with the rendered environment block, injecting the summary immediately before the first user turn.

Caching and Stability Mechanisms

To ensure deterministic behavior across restarts, Reasonix implements a caching layer. The ProbeResult is marshaled to JSON and stored at $REASONIX_HOME/environment/probes-<hash>.json. Subsequent startups read this cached snapshot instead of re-executing subprocess calls, unless the cache is invalidated or a probe fails.

Security considerations are handled in internal/secrets/redact.go, which filters sensitive patterns (such as variables ending in _TOKEN or containing API_KEY) from the environment snapshot before caching or injection.

Practical Implementation Examples

Accessing the Environment Summary Programmatically

You can retrieve the same environment data that Reasonix injects into the prompt using the environment package:

package main

import (
    "fmt"
    "reasonix/internal/environment"
)

func main() {
    // Run the probe (uses cached result if available)
    env, err := environment.Probe()
    if err != nil {
        panic(err)
    }

    fmt.Println("=== Environment Summary ===")
    fmt.Printf("OS:          %s\n", env.OS)
    fmt.Printf("Shell:       %s (%s)\n", env.Shell, env.ShellVersion)
    fmt.Printf("Path:        %s\n", env.ShellPath)
    fmt.Println("Env vars:")
    for _, kv := range env.EnvVars {
        fmt.Println("  ", kv)
    }
}

Overriding the Injected Summary

For testing or custom deployments, you can override the detected environment by specifying an override value in your reasonix.toml:

[environment]
override = """
OS = "custom-linux"
Shell = "bash"
ShellVersion = "5.2"
Env = ["FOO=bar"]
"""

When this field is present, the renderer uses it instead of executing the probe logic.

Disabling Environment Injection

To disable the automatic injection for debugging purposes, clear the system prompt configuration:

[agent]
system_prompt = ""

When system_prompt is empty, Reasonix falls back to its built-in prompt without the environment summary block.

Summary

• Host Probing: internal/environment/probe.go executes Probe() to detect OS type (via runtime.GOOS and uname), shell executable (via sandbox.ResolveShell), and environment variables.
• Result Caching: Probe results are marshaled to JSON and stored at $REASONIX_HOME/environment/probes-<hash>.json to ensure stable, deterministic prompts across sessions.
• TOML Rendering: renderEnvironmentConfig in internal/config/render.go formats the data as an [environment] TOML block.
• Prompt Injection: BuildSystemPrompt in internal/agent/prompt.go appends the rendered block to the system prompt before the first user interaction.
• Security Filtering: internal/secrets/redact.go automatically removes sensitive environment variables (matching patterns like *_TOKEN or *API_KEY*) before caching or injection.

Frequently Asked Questions

How does Reasonix detect the operating system and shell?

Reasonix uses runtime.GOOS combined with platform-specific commands like uname -s on Unix or registry reads on Windows. For shell detection, it examines the $SHELL environment variable (or %COMSPEC% on Windows), falls back to common defaults such as /bin/bash or powershell.exe, and executes version queries like bash --version to populate the ProbeResult struct with accurate metadata.

Where is the environment summary cached?

The probe results are marshaled to JSON and stored at $REASONIX_HOME/environment/probes-<hash>.json. This cache is reused on subsequent startups unless invalidated, eliminating the need for repeated subprocess calls and ensuring consistent prompt content across restarts.

Can I customize or disable the environment summary injection?

Yes. You can provide a custom TOML block using the config.Environment.Override setting in reasonix.toml. To disable injection entirely, set system_prompt = "" in the [agent] section, which causes Reasonix to use a built-in prompt without the environment block.

How does Reasonix prevent sensitive data from leaking into the prompt?

Before caching or injection, the internal/secrets/redact.go module filters the environment variable list to remove entries matching secret-sensitive patterns, such as keys ending in _TOKEN or containing API_KEY. This ensures credentials and private tokens never reach the model context window.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}