Advanced

System Prompt

How agentOS injects context into agent sessions.

These internal architecture docs are mostly generated and maintained by LLMs, then reviewed by humans. They are intentionally verbose; use your preferred LLM to ask focused questions about the architecture as needed.

agentOS automatically injects a system prompt into every agent session that describes the VM environment and available commands and bindings. The prompt is additive and never replaces the agent’s own instructions (CLAUDE.md, AGENTS.md, etc.).

The base prompt is embedded in the sidecar (not written to a file inside the VM). At session start the sidecar assembles the base prompt with your additional instructions and generated binding docs, then injects the result into the agent adapter’s launch arguments (for example, --append-system-prompt for Pi).

Customization

additionalInstructions appends session-specific text after the base OS prompt and before the generated binding docs, rather than replacing the agent’s own instructions.
skipOsInstructions suppresses the base OS prompt while still injecting the generated binding docs.

await agent.openSession({
	agent: "pi",
	env: { ANTHROPIC_API_KEY: process.env.ANTHROPIC_API_KEY! },
	// Extra instructions appended to the agent system prompt
	additionalInstructions: "Always write tests before implementation.",
	// Suppress the base OS prompt (binding docs are still injected)
	skipOsInstructions: true,
});