Core concepts
Raw is configured in one JSON file, config.json. Its main parts are models, agents and the capabilities that agents select. The sections below define each part and link to the page with the details.
Models
Section titled “Models”A model entry (models.<alias>) describes one connection to an upstream model. It names the provider, the wire method, the exact model ID sent to the service, the endpoint, where the credential comes from, and optional metadata such as the context window and whether the model accepts images.
A model alias such as local is only a name inside your config. The model_id value is sent to the service unchanged.
See Models and agents.
Agents
Section titled “Agents”An agent (agents.<name>) is a runnable configuration. It selects one model alias and sets everything a run needs: the system prompt, tools, skills, hooks, variables, limits and request options.
Several agents can use the same model with different tools or settings. The default_agent field chooses the agent when you do not pass --agent. You can also set RAW_AGENT in the environment.
See Models and agents.
A tool is an action the model can request, such as reading a file, writing a file, or running a shell command. Raw ships eleven bundled tools, including read_file, write_file, bash, list_skills, load_skill, list_vars and read_var.
An agent exposes only the tools it lists in tools.use, in the order listed. Tool IDs use a source prefix: builtin/ for bundled tools, local/ for tools in your config directory, agent/ for tools beside the selected config file, and mcp/<server>/<tool> for MCP tools.
Tools run with your operating system permissions. Read Permissions before you rely on tool rules.
See Tools.
Skills
Section titled “Skills”A skill is a Markdown instruction file (SKILL.md) that the model can load when it needs it. The model first lists the skills an agent selected, then loads only the ones that apply to the task. Raw ships seven setup skills, for example for configuring Raw or creating hooks.
Skills guide the model. They do not enforce a fixed sequence of steps.
See Skills and Skill authoring.
A hook is a command that Raw runs at a named event. The events include SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, PostToolUseFailure, Stop and SessionEnd. An agent selects hooks in hooks.use, and they run in that order.
Hook commands run with your operating system permissions. A PreToolUse hook can block a tool call.
See Hooks.
MCP servers
Section titled “MCP servers”An MCP server is an external tool provider that speaks the Model Context Protocol. You define servers in the top-level mcp.servers object. A server does nothing until an agent selects one of its tools, so unselected servers are never started.
Raw supports local stdio servers and remote Streamable HTTP servers.
See MCP.
Variables
Section titled “Variables”A variable is a named, read-only value that an agent can read at run time, such as the current UTC time or a value from an environment variable. Variables are declared in the top-level vars object. An agent selects the ones it may use in its vars list.
Use raw vars list and raw vars get NAME to inspect them without starting a model.
See Variables.
Packages
Section titled “Packages”A package bundles agents, tools, skills, hooks, variables and MCP definitions into one .rawpkg archive. You export a configured agent, pack it, and install it on another machine. The recipient then binds the package agent to their own model with raw agent add.
See Packages.
Sessions
Section titled “Sessions”A session is a saved conversation. Raw stores each session with its history and the context the model uses, so you can resume it later from the terminal or the dashboard. Sessions expire after a retention period measured from their last activity, seven days by default.
See Sessions.
Next steps
Section titled “Next steps”- Quickstart runs a first task.
- Configuration reference lists every field.