---
title: "Settings · intentic sandbox API"
description: "The sandbox's own configuration, plus what it has saved you and which rules fired. Every route in the settings group of the intentic sandbox API, with its input, its answer and a playground."
url: "https://intentic.dev/api/settings/"
---

Agent setup

# Settings

The sandbox's own configuration, plus what it has saved you and which rules fired

**On this page (5 sections)**

- [How this sandbox is configured](#settings-get)
- [Change the sandbox settings](#settings-set)
- [What the token-saving measures were worth](#settings-savings)
- [Read a built-in system prompt](#settings-builtinPrompt)
- [When each rule last did something](#settings-firings)

Read and write the settings that govern how agents behave here. The other three routes are read-only reports on their effects: what the token-saving measures were actually worth, the text behind a built-in prompt, and when each rule last did something.

**GET`/settings` How this sandbox is configured**

Every setting that governs how agents behave here, with the defaults filled in for anything nobody has chosen.

### What you send

Nothing. Call it as it is.

### What comes back

| Field | Type |
| --- | --- |
| `stableSystemPrompt` Keep the instructions identical between turns… | boolean |
| `skills` Which skills are switched on | string[] |
| `hashlineEdits` Have the agent edit files by… | boolean |
| `terseOutput` Ask the agent to say less | boolean |
| `terseHoldout` What share of turns to run… | number |
| `systemPromptMode` Which instructions the agent starts from:… | "intentic" | "claude" | "custom" |
| `systemPrompt` Your own instructions, used only when… | string |
| `iqSearch` Teach the agent how to use… | boolean |
| `iqSearchHoldout` What share of conversations to run… | number |
| `workspaceMap` Open every conversation with a map… | boolean |
| `outputCleaners` Which command outputs to trim before… | string |
| `outputHoldout` What share of commands to leave… | number |
| `quickModel` Which models do the small automatic… | string[] |
| `changelogRepos` Which repositories keep a changelog, and… | string[] |
| `agentRunModels` Which models run the work a… | string[] |
| `agentRunEffort` How hard those runs should think | string |
| `autoTier` Whether an easy-looking turn may run… | "off" | "shadow" | "on" |
| `autoTierEagerness` How readily a turn counts as… | "cautious" | "balanced" | "eager" |
| `autoFastModels` Which cheaper model a downgraded turn… | string[] |
| `agentRetentionDays` How many days a finished conversation… | number |
| `resumeAfterOutage` Whether a turn killed by the… | boolean |
| `autoResumeOnRestart` Whether a turn killed by the… | boolean |
| `rules` Standing instructions you give the sandbox… | object[] |
| `id` | string |
| `label` | string |
| `moment` | "turn.ending" | "push.starting" | "agent.finished" |
| `when` | object |
| `repo` | string |
| `paths` | string[] |
| `outcome` | "clean" | "error" | "conflict"[] |
| `action` | object |
| `when kind is "command"` | shape |
| `command` | string |
| `timeoutMs` | number |
| `when kind is "instruct"` | shape |
| `text` | string |
| `when kind is "verdict"` | shape |
| `verdict` | "allow" | "hold" |
| `when kind is "builtin"` | shape |
| `name` | "verify-edits" |
| `enabled` | boolean |
| `automationFailureLimit` How many failures in a row… | number |
| `admission` Whether work started from outside may… | object |
| `schedule` | "allow" | "hold" | "deny" |
| `event` | "allow" | "hold" | "deny" |
| `listener` | "allow" | "hold" | "deny" |
| `webchat` | "allow" | "hold" | "deny" |
| `workspace` | "allow" | "hold" | "deny" |
| `workflow` | "allow" | "deny" |
| `actionRules` What an agent may do out… | object |
| `commandRules` What an agent may run inside… | object |
| `subagentsAtOnce` How many helper agents may work… | number |
| `subagentsPerTurn` How many a single turn may… | number |
| `subagentDepth` How many levels deep the delegation… | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/settings" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.settings.get();
```

**POST`/settings` Change the sandbox settings**

Writes the settings whole, so send the complete object rather than the fields you changed.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `stableSystemPrompt` Keep the instructions identical between turns… | boolean | body |
| `skills` Which skills are switched on | string[] | body |
| `hashlineEdits` Have the agent edit files by… | boolean | body |
| `terseOutput` Ask the agent to say less | boolean | body |
| `terseHoldout` What share of turns to run… | number | body |
| `systemPromptMode` Which instructions the agent starts from:… | "intentic" | "claude" | "custom" | body |
| `systemPrompt` Your own instructions, used only when… | string | body |
| `iqSearch` Teach the agent how to use… | boolean | body |
| `iqSearchHoldout` What share of conversations to run… | number | body |
| `workspaceMap` Open every conversation with a map… | boolean | body |
| `outputCleaners` Which command outputs to trim before… | string | body |
| `outputHoldout` What share of commands to leave… | number | body |
| `quickModel` Which models do the small automatic… | string[] | body |
| `changelogRepos` Which repositories keep a changelog, and… | string[] | body |
| `agentRunModels` Which models run the work a… | string[] | body |
| `agentRunEffort` How hard those runs should think | string | body |
| `autoTier` Whether an easy-looking turn may run… | "off" | "shadow" | "on" | body |
| `autoTierEagerness` How readily a turn counts as… | "cautious" | "balanced" | "eager" | body |
| `autoFastModels` Which cheaper model a downgraded turn… | string[] | body |
| `agentRetentionDays` How many days a finished conversation… | number | body |
| `resumeAfterOutage` Whether a turn killed by the… | boolean | body |
| `autoResumeOnRestart` Whether a turn killed by the… | boolean | body |
| `rules` Standing instructions you give the sandbox… | object[] | body |
| `id` required | string | body |
| `label` required | string | body |
| `moment` required | "turn.ending" | "push.starting" | "agent.finished" | body |
| `when` | object | body |
| `repo` | string | body |
| `paths` | string[] | body |
| `outcome` | "clean" | "error" | "conflict"[] | body |
| `action` required | object | body |
| `when kind is "command"` | shape | body |
| `command` required | string | body |
| `timeoutMs` | number | body |
| `when kind is "instruct"` | shape | body |
| `text` required | string | body |
| `when kind is "verdict"` | shape | body |
| `verdict` required | "allow" | "hold" | body |
| `when kind is "builtin"` | shape | body |
| `name` required | "verify-edits" | body |
| `enabled` | boolean | body |
| `automationFailureLimit` How many failures in a row… | number | body |
| `admission` Whether work started from outside may… | object | body |
| `schedule` | "allow" | "hold" | "deny" | body |
| `event` | "allow" | "hold" | "deny" | body |
| `listener` | "allow" | "hold" | "deny" | body |
| `webchat` | "allow" | "hold" | "deny" | body |
| `workspace` | "allow" | "hold" | "deny" | body |
| `workflow` | "allow" | "deny" | body |
| `actionRules` What an agent may do out… | object | body |
| `commandRules` What an agent may run inside… | object | body |
| `subagentsAtOnce` How many helper agents may work… | number | body |
| `subagentsPerTurn` How many a single turn may… | number | body |
| `subagentDepth` How many levels deep the delegation… | number | body |

### What comes back

| Field | Type |
| --- | --- |
| `ok` Always true | true |

Try it answered in this tab

curl

```bash
curl -X POST "$SANDBOX/settings" \
 -H "x-intentic-control: $INTENTIC_TOKEN" \
 -H "content-type: application/json" \
 -d '{"stableSystemPrompt":false,"skills":["…","…"],"hashlineEdits":false,"terseOutput":false,"terseHoldout":0,"systemPromptMode":"intentic","systemPrompt":"","iqSearch":false,"iqSearchHoldout":0,"workspaceMap":false,"outputCleaners":"off","outputHoldout":0,"quickModel":["…","…"],"changelogRepos":["…","…"],"agentRunModels":["…","…"],"agentRunEffort":"","autoTier":"off","autoTierEagerness":"cautious","autoFastModels":["…","…"],"agentRetentionDays":3,"resumeAfterOutage":false,"autoResumeOnRestart":false,"rules":[{"id":"a1b2c3d4","label":"Nightly changelog","moment":"turn.ending","when":{"repo":"root","paths":["src/app.ts","README.md"],"outcome":["clean","error"]},"action":{"kind":"command","command":"pnpm dev","timeoutMs":900000},"enabled":true},{"id":"e5f6a7b8","label":"Release notes","moment":"push.starting","when":{"repo":"site","paths":["src/app.ts","README.md"],"outcome":["clean","error"]},"action":{"kind":"command","command":"pnpm build","timeoutMs":900000},"enabled":true}],"automationFailureLimit":0,"admission":{"schedule":"allow","event":"allow","listener":"allow","webchat":"allow","workspace":"allow","workflow":"allow"},"actionRules":{"src/app.ts":"allow","README.md":"hold"},"commandRules":{"src/app.ts":"allow","README.md":"hold"},"subagentsAtOnce":20,"subagentsPerTurn":200,"subagentDepth":3}'
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.settings.set({
 "stableSystemPrompt": false,
 "skills": [
 "…",
 "…"
 ],
 "hashlineEdits": false,
 "terseOutput": false,
 "terseHoldout": 0,
 "systemPromptMode": "intentic",
 "systemPrompt": "",
 "iqSearch": false,
 "iqSearchHoldout": 0,
 "workspaceMap": false,
 "outputCleaners": "off",
 "outputHoldout": 0,
 "quickModel": [
 "…",
 "…"
 ],
 "changelogRepos": [
 "…",
 "…"
 ],
 "agentRunModels": [
 "…",
 "…"
 ],
 "agentRunEffort": "",
 "autoTier": "off",
 "autoTierEagerness": "cautious",
 "autoFastModels": [
 "…",
 "…"
 ],
 "agentRetentionDays": 3,
 "resumeAfterOutage": false,
 "autoResumeOnRestart": false,
 "rules": [
 {
 "id": "a1b2c3d4",
 "label": "Nightly changelog",
 "moment": "turn.ending",
 "when": {
 "repo": "root",
 "paths": [
 "src/app.ts",
 "README.md"
 ],
 "outcome": [
 "clean",
 "error"
 ]
 },
 "action": {
 "kind": "command",
 "command": "pnpm dev",
 "timeoutMs": 900000
 },
 "enabled": true
 },
 {
 "id": "e5f6a7b8",
 "label": "Release notes",
 "moment": "push.starting",
 "when": {
 "repo": "site",
 "paths": [
 "src/app.ts",
 "README.md"
 ],
 "outcome": [
 "clean",
 "error"
 ]
 },
 "action": {
 "kind": "command",
 "command": "pnpm build",
 "timeoutMs": 900000
 },
 "enabled": true
 }
 ],
 "automationFailureLimit": 0,
 "admission": {
 "schedule": "allow",
 "event": "allow",
 "listener": "allow",
 "webchat": "allow",
 "workspace": "allow",
 "workflow": "allow"
 },
 "actionRules": {
 "src/app.ts": "allow",
 "README.md": "hold"
 },
 "commandRules": {
 "src/app.ts": "allow",
 "README.md": "hold"
 },
 "subagentsAtOnce": 20,
 "subagentsPerTurn": 200,
 "subagentDepth": 3
});
```

**GET`/settings/savings` What the token-saving measures were worth**

Measured rather than estimated: what each mechanism actually saved over a range of days. The same day range the spending ledger takes, so one calendar filters both.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `from` First day to include, as YYYY-MM-DD… | string | query |
| `to` Last day to include, as YYYY-MM-DD… | string | query |

### What comes back

| Field | Type |
| --- | --- |
| `input` | object |
| `updatedAt` | number |
| `commands` | number |
| `rawTokens` | number |
| `emittedTokens` | number |
| `savedPct` | number |
| `perCleaner` | object[] |
| `id` | string |
| `commands` | number |
| `savedTokens` | number |
| `holdout` | object |
| `cleaned` | number |
| `heldOut` | number |
| `measuredSavedPct` | number |
| `gaps` | object[] |
| `command` | string |
| `commands` | number |
| `tokens` | number |
| `output` | object |
| `metrics` | object[] |
| `metric` | "proseChars" | "searchCalls" | "openingSearches" |
| `on` | object |
| `turns` | number |
| `mean` | number |
| `off` | object |
| `turns` | number |
| `mean` | number |
| `controlTurnsNeeded` | number |
| `marginPct` | number |
| `deltaPct` | number |
| `saved` | number |
| `minTurns` | number |
| `sampleUnit` | "turns" | "conversations" |
| `cohort` | string |
| `search` | object |
| `metrics` | object[] |
| `metric` | "proseChars" | "searchCalls" | "openingSearches" |
| `on` | object |
| `turns` | number |
| `mean` | number |
| `off` | object |
| `turns` | number |
| `mean` | number |
| `controlTurnsNeeded` | number |
| `marginPct` | number |
| `deltaPct` | number |
| `saved` | number |
| `minTurns` | number |
| `sampleUnit` | "turns" | "conversations" |
| `cohort` | string |
| `tier` | object |
| `judged` | number |
| `fast` | number |
| `atStakeUsd` | number |
| `routed` | number |
| `routedUsd` | number |
| `escalated` | number |
| `denied` | number |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/settings/savings" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.settings.savings();
```

**GET`/settings/system-prompt/{base}` Read a built-in system prompt**

The actual text behind one of the built-in modes, so a settings screen can show the prompt instead of asking anyone to trust a description of it, and so either can be forked into a custom one.

### What you send

| Field | Type | Where |
| --- | --- | --- |
| `base` required | "intentic" | "claude" | address |

### What comes back

| Field | Type |
| --- | --- |
| `text` | string |
| `version` | string |

Try it answered in this tab

curl

```bash
curl "$SANDBOX/settings/system-prompt/intentic" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.settings.builtinPrompt({
 "base": "intentic"
});
```

**GET`/settings/rule-firings` When each rule last did something**

A separate read rather than a field on the settings, because a rule firing is not somebody editing anything: folding it in would turn every firing into a settings write and put a self-changing value inside the object a screen edits.

### What you send

Nothing. Call it as it is.

### What comes back

A plain value rather than an object. The example below is the whole of it.

Try it answered in this tab

curl

```bash
curl "$SANDBOX/settings/rule-firings" \
 -H "x-intentic-control: $INTENTIC_TOKEN"
```

TypeScript

```typescript
import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.settings.firings();
```

More in Agent setup

[Previous ← Extensions](https://intentic.dev/api/extensions/)