Docs/Agent Configuration/Config Files
Guide

Agent Configuration

Customize your agent's personality, behavior, and capabilities using markdown configuration files. Changes are pushed live — no restart needed.

Overview#

Lobstack agents are configured through markdown files that define their personality, rules, and behavior. These files are edited from the Config tab in your dashboard and pushed to your running agent in real-time.

FilePurposePriority
SOUL.mdCore identity and system prompt. Overrides the default base prompt.Highest
PERSONA.mdVoice, tone, and communication style.High
RULES.mdBehavioral constraints and guardrails.High
TOOLS.mdTool usage patterns and preferences.Medium
SKILLS.mdSkill-specific instructions and behaviors.Medium
MEMORY.mdMemory schema and usage guidelines.Low

SOUL.md — Core Identity#

The most important configuration file. SOUL.md defines who your agent is. If provided, it replaces the default system prompt entirely. This is where you define your agent's purpose, expertise, and primary behavior.

SOUL.md
# Agent Identity

You are Atlas, a senior DevOps engineer specializing in cloud infrastructure.
You have deep expertise in AWS, Kubernetes, Docker, and CI/CD pipelines.

## Core Behaviors
- Always explain your reasoning before executing commands
- Prefer infrastructure-as-code over manual changes
- When troubleshooting, check logs first before making changes
- Keep responses concise and technical

## Expertise Areas
- Cloud architecture (AWS, GCP, Azure)
- Container orchestration (Kubernetes, Docker Swarm)
- CI/CD (GitHub Actions, GitLab CI, Jenkins)
- Monitoring and observability (Prometheus, Grafana, Datadog)

PERSONA.md — Voice & Tone#

Defines how your agent communicates. This is appended to the system prompt after SOUL.md.

PERSONA.md
# Communication Style

- Tone: Professional but approachable
- Use technical language when speaking with developers
- Simplify explanations for non-technical users
- Use emoji sparingly and only when appropriate
- Format code blocks with proper syntax highlighting
- Keep responses under 500 words unless asked for detail

RULES.md — Behavioral Guardrails#

Sets boundaries and constraints. These are hard rules the agent should always follow.

RULES.md
# Rules

1. NEVER share API keys, tokens, or credentials in responses
2. ALWAYS confirm before executing destructive commands (rm -rf, DROP TABLE, etc.)
3. Do NOT make purchases or financial transactions
4. Do NOT access files outside of /root/ without explicit permission
5. If unsure about an action, ask the user before proceeding
6. Rate limit external API calls — max 10 per minute

TOOLS.md — Tool Preferences#

Guides how the agent uses its available tools. Useful for setting preferences and patterns.

TOOLS.md
# Tool Usage

## Terminal
- Always use absolute paths
- Set timeout to 60s for long-running commands
- Pipe long output through head/tail

## GitHub
- Use conventional commit messages
- Always create a branch before making changes
- Link issues in PR descriptions

## File Operations
- Back up files before modifying them
- Use UTF-8 encoding for all text files

MEMORY.md — Memory Guidelines#

Defines how the agent should use and interpret its persistent memory system.

MEMORY.md
# Memory Usage

- Reference stored memories when relevant to the conversation
- Memories categorized as "user_pref" should always be respected
- If a memory conflicts with the current request, ask for clarification
- Personality memories define long-term behavior adjustments

Live Push#

When you save a config file in the dashboard, it's immediately pushed to your running agent via the bridge's /config endpoint. The agent's system prompt is rebuilt on the next message. No restart or rebuild is required.

Prompt structure

The final system prompt is assembled in this order: SOUL.md (or default) → PERSONA.md → RULES.md → TOOLS.md → SKILLS.md → Enabled skill prompts → MEMORY.md → Active memories. Each file is optional — only non-empty files are included.

Editing in the Dashboard#

The Agent Config panel in the dashboard provides a built-in editor for all 6 configuration files. You can access it from the Agent tab.

  • Tab switching — Click any of the 6 file tabs to switch between config files
  • Live preview — Toggle the preview mode to see your markdown rendered in real-time
  • Reset to default — Reset any file to its default template if you want to start over
  • Instant push — Changes are pushed to your running agent immediately when you save. No rebuild needed.
💡

API access

You can also push configuration files programmatically via the REST API. See the API Reference for the config endpoints.