Advanced

System Prompt

Configure the context agentOS injects into coding-agent sessions, including environment details, available tools, and workspace guidance.

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, available commands, and host functions. 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 host-function 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 host-function docs, rather than replacing the agent’s own instructions.
skipOsInstructions suppresses the base OS prompt while still injecting the generated host-function docs.
For Claude Code, ACP_SYSTEM_PROMPT_MODE=replace in the session env replaces Claude Code’s built-in system prompt with the assembled prompt. See Claude Code.

await agent.sessions.open({
	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 (host-function docs are still injected).
	skipOsInstructions: true,
});