> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paddock.build/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Set an agent's system prompt, environment, permissions, and model, and know which settings are fixed for each session.

An agent's configuration is its template's, with the agent's own values applied on top: the agent's value wins on a shared name. Some settings reach running sessions; others are fixed when a session is created.

## What is fixed per session

| Setting | Changed on the agent with | Reaches |
| - | - | - |
| Model | `modelSetting.set` | Running sessions, between turns |
| MCP servers, marketplaces, plugins | The [capability collections](https://docs.paddock.build/guides/capabilities.md) | Running sessions, between turns |
| System prompt | `systemPrompt.set` | Sessions created afterwards |
| Environment | `env.add`, `update`, `delete` | Sessions created afterwards |
| Permissions | `permissions.set` | Sessions created afterwards |
| Small model (Claude Code) | `smallModelSetting.set` | Sessions created afterwards |

When a session is created, paddock composes its **session settings** from the agent's effective configuration at that moment: the system prompt, the environment, the permissions, and Claude Code's small model. They never change for that session. The harnesses read these values only when a process or conversation starts, so fixing them per session means every restart and resume of a session runs on the same values, and no change ever needs a harness restart. Create a new session to pick up new values.

A session's working directory (`cwd`) is fixed at creation too; see [Agents and sessions](https://docs.paddock.build/guides/agents-and-sessions.md#create-a-session).

## System prompt

The system prompt is text appended to the harness's own system prompt in every turn; it is never shown as a message. It comes from three places:

1. The template's `system_prompt`.
2. The agent's own, which replaces the template's when set.
3. The `systemPrompt` given to `sessions.create`, appended after a blank line.

The result is stored as the session's `systemPrompt` (`null` when all are empty), at most 64 KiB.

```go Go theme={null}
prompt := "You maintain Acme's web app. Prefer small pull requests."
_, err := agent.SystemPrompt.Set(ctx, prompt)
if err != nil {
	return err
}
setting, err := agent.SystemPrompt.Get(ctx)
if err != nil {
	return err
}
fmt.Println(setting.Source) // "agent"

// Restore the template's prompt for sessions created from now on.
_, err = agent.SystemPrompt.Delete(ctx)
```

```python Python theme={null}
agent.system_prompt.set("You maintain Acme's web app. Prefer small pull requests.")
setting = agent.system_prompt.get()
print(setting.source)  # "agent"

# Restore the template's prompt for sessions created from now on.
agent.system_prompt.delete()
```

```ts TypeScript theme={null}
await agent.systemPrompt.set("You maintain Acme's web app. Prefer small pull requests.");
const setting = await agent.systemPrompt.get();
console.log(setting.source); // "agent"

// Restore the template's prompt for sessions created from now on.
await agent.systemPrompt.delete();
```

`get`, `set`, and `delete` each return the effective value with its `source`, `template` or `agent`.

> [!TIP]
>
> Put hard rules about output, such as a required format, both in the system prompt and in the messages that ask for the work. Agents follow rules repeated in the request more reliably.

## Environment

On Claude Code, environment variables reach the harness and every command it runs. On Codex, they reach every command Codex runs but not the Codex process itself.

```go Go theme={null}
_, err := agent.Env.Add(ctx, paddock.EnvEntry{Name: "NODE_ENV", Value: "production"})
if err != nil {
	return err
}
_, err = agent.Env.Update(ctx, "NODE_ENV", paddock.EnvEntry{Name: "NODE_ENV", Value: "staging"})
if err != nil {
	return err
}
err = agent.Env.Delete(ctx, "NODE_ENV")
```

```python Python theme={null}
agent.env.add({"name": "NODE_ENV", "value": "production"})
agent.env.update("NODE_ENV", {"name": "NODE_ENV", "value": "staging"})
agent.env.delete("NODE_ENV")
```

```ts TypeScript theme={null}
await agent.env.add({ name: "NODE_ENV", value: "production" });
await agent.env.update("NODE_ENV", { name: "NODE_ENV", value: "staging" });
await agent.env.delete("NODE_ENV");
```

* Names match `^[A-Za-z_][A-Za-z0-9_]*$`, up to 128 bytes; values are UTF-8 up to 16 KiB.
* These names are reserved, because paddock sets them for the harness: `PADDOCK_*`, `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_BASE_URL`, `CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `HOME`, and `PATH`. Using one is `400`.
* The collection rules of [Capabilities](https://docs.paddock.build/guides/capabilities.md) apply: `add` of a template's name creates the agent's override, and `delete` restores the template's value.

## Permissions

Permissions are `allow` and `deny` rules in the syntax of the agent's harness. paddock passes them to the harness as they are and does not interpret them: on Claude Code they become the `allow` and `deny` lists of its settings, such as `Bash(npm run test:*)`.

```go Go theme={null}
effective, err := agent.Permissions.Set(ctx, paddock.PermissionsSpec{
	Allow: []string{"Bash(npm run test:*)"},
	Deny:  []string{"Bash(git push:*)"},
})
if err != nil {
	return err
}
fmt.Println(effective.Deny)
```

```python Python theme={null}
effective = agent.permissions.set({"allow": ["Bash(npm run test:*)"], "deny": ["Bash(git push:*)"]})
print(effective.deny)
```

```ts TypeScript theme={null}
const effective = await agent.permissions.set({ allow: ["Bash(npm run test:*)"], deny: ["Bash(git push:*)"] });
console.log(effective.deny);
```

`set` replaces the agent's own permissions and returns the effective ones: the effective `deny` is the template's and the agent's together, and the effective `allow` is the agent's once it has set one, otherwise the template's.

## Model and small model

The model is the one setting of this page that reaches running sessions: a change is applied between turns, so a turn always finishes on the model it started with. Claude Code's small model, used for background requests and for subagents that ask for a smaller model, is a session setting.

```go Go theme={null}
_, err := agent.ModelSetting.Set(ctx, "claude-sonnet")
if err != nil {
	return err
}
_, err = agent.SmallModelSetting.Set(ctx, "claude-haiku")
```

```python Python theme={null}
agent.model_setting.set("claude-sonnet")
agent.small_model_setting.set("claude-haiku")
```

```ts TypeScript theme={null}
await agent.modelSetting.set("claude-sonnet");
await agent.smallModelSetting.set("claude-haiku");
```

The agent's `model` field is always the effective model. `delete()` restores the template's value. Which names you can use is on [Models](https://docs.paddock.build/guides/models.md).

## Save the result

When an agent's configuration is what you want for new agents, export it and save it as a template; see [Templates](https://docs.paddock.build/guides/templates.md#save-an-agent-as-a-template).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.