Runtime defaults

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.

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 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:

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 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():

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. For cleanup behavior in a script or service, see lifecycle and cleanup. spawn.keepScratch: true preserves temporary state for debugging. It is not a persistence strategy. See troubleshooting before enabling it.

Get started

Models and conversations

Tools and extensions

Control and observe

Cookbooks

Run in an application

Help and migration

What happens automatically

Configuration isolation is not a tool sandbox

Supply credentials explicitly when needed

Deliberately use host configuration

Choose the right state lifetime

​What happens automatically

​Configuration isolation is not a tool sandbox

​Supply credentials explicitly when needed

​Deliberately use host configuration

​Choose the right state lifetime

What happens automatically

Configuration isolation is not a tool sandbox

Supply credentials explicitly when needed

Deliberately use host configuration

Choose the right state lifetime