> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Runtime defaults

> Know what happens automatically, and which settings you may want to change.

**Isolation is already on.** You do not need to configure it to follow the quickstart or use the SDK in an application. This page is for understanding defaults and deliberately changing them.

## What happens automatically

When you use `Agent`, `query()`, or a locally spawned `createAgentClient()`, the SDK starts a runtime with temporary configuration and state directories. It does not automatically read your personal authentication files or agent configuration. A session's `settingSources` is empty unless you choose otherwise.

| Default | What it means for your application |
| - | - |
| Isolated local runtime | Personal runtime configuration and stored credentials are not implicitly imported. |
| Neutral agent instructions | You choose the agent's role; a coding persona is not forced on every task. |
| Explicit settings discovery | Project instructions, filesystem plugins, and skills are not automatically loaded. Programmatic definitions still work. |
| Provider environment forwarding | Supported provider variables, including `OPENAI_API_KEY` and `ANTHROPIC_API_KEY`, are available to the runtime. |
| Temporary state | The owned scratch directory is removed when its local runtime closes successfully. |

The high-level `Agent` and `query()` facade also disables title generation, language servers, and formatters by default. It hides the interactive `question`, `todowrite`, and `skill` tools unless your tool policy replaces those defaults. Other tools are subject to your selected tool list and permissions. See [built-in tools](https://cognitio-agent.mintlify.site/concepts/built-in-tools.md).

## Configuration isolation is not a tool sandbox

File, shell, and network tools run with the runtime process's operating-system access. `cwd` selects a working directory; it does not create a filesystem security boundary. Your custom tool callbacks run inside your application process.

Choose [tool permissions](https://cognitio-agent.mintlify.site/concepts/permissions.md) for your workflow. If an application requires operating-system confinement, run it in a container or another sandbox you operate.

## Supply credentials explicitly when needed

A supported key in your environment is sufficient for the quickstart. For a different variable name or an application-managed credential, pass `spawn.auth`:

```ts theme={null}
import { Agent } from "cognitio-agent-sdk"

const key = process.env.MY_OPENAI_KEY
if (!key) throw new Error("Set MY_OPENAI_KEY before running this example.")

const agent = new Agent({
  model: "openai/gpt-4.1-mini",
  disallowedTools: ["*"],
  spawn: { auth: { openai: { type: "api", key } } },
})

try {
  console.log((await agent.run("Say hello in one sentence.")).text)
} finally {
  await agent.close()
}
```

Explicit `spawn` options give this Agent a dedicated runtime, so `close()` also stops that runtime. The example still uses the default isolated mode.

`spawn.passEnv` forwards named host variables; `spawn.env` supplies explicit child values. Arbitrary `*_API_KEY` names and `GITHUB_TOKEN` are not automatically forwarded. Standard proxy variables and `AWS_*`, `AZURE_*`, `GOOGLE_*`, and `OTEL_*` have forwarding rules. See [SpawnOptions](https://cognitio-agent.mintlify.site/api-reference/interfaces/SpawnOptions.md) for the options and reserved variables.

## Deliberately use host configuration

Use this only when the agent is intended to behave like a tool running in your existing local environment. The following options are a configuration fragment to pass to `new Agent()`:

```ts theme={null}
import type { AgentOptions } from "cognitio-agent-sdk"

const hostConfiguration = {
  spawn: { isolated: false },
  settingSources: ["user", "project", "local"],
  systemPrompt: { type: "preset", preset: "default" },
} satisfies AgentOptions
```

These choices do different things: non-isolated spawn enables host configuration, `settingSources` selects discovered settings, and the preset chooses the coding-oriented system prompt. You do not need any of them for normal SDK use.

## Choose the right state lifetime

A session ID can be resumed while its backing runtime and database remain available. Default isolated scratch is temporary, so keeping the ID alone does not preserve a conversation after runtime shutdown.

For a service that needs longer-lived sessions, operate a persistent runtime and connect in [remote mode](https://cognitio-agent.mintlify.site/cookbook/remote.md). For cleanup behavior in a script or service, see [lifecycle and cleanup](https://cognitio-agent.mintlify.site/cookbook/lifecycle.md).

`spawn.keepScratch: true` preserves temporary state for debugging. It is not a persistence strategy. See [troubleshooting](https://cognitio-agent.mintlify.site/troubleshooting.md) before enabling it.


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