Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

Storage layout

Agent files live under a Toolang root. The default root is ~/.toolang.

Command surfaces can override the root with --root or TOOLANG_ROOT.

A single root can contain multiple agent homes:

$TOOLANG_ROOT/
├── .env
├── config.toml
├── {cap dirs}
├── {runtime dirs}
└── agents/
    └── <agent>/
        ├── .env
        ├── config.toml
        ├── agent.too
        ├── {cap dirs}
        ├── {job dirs}
        └── {runtime dirs}

Scopes

Toolang resolves files from three scopes: root, home, and here.

Files under the root are shared by all agents in that root. Files under an agent home are private to that agent. Inline definitions and references inside the current .too source are private to the running agent.

ScopeLocationVisibility
root$TOOLANG_ROOT/Shared by all agents in the same root
home$TOOLANG_ROOT/agents/<agent>/Private to one agent
hereagent.too or the current .too sourcePrivate to the running agent

Placement

Toolang uses an agent's placement to decide where its root and home live.

An agent can have one of three placements:

  1. Resident agents are durable local agents stored under a selected Toolang root.
  2. Visiting agents are remote agents materialized under a runtime-managed temporary root.
  3. Roaming agents are local .too scripts run from a workspace directory.

root and home are resolved as follows:

PlacementRootHome
ResidentTOOLANG_ROOT, or ~/.toolang by default<root>/agents/<agent>/
VisitingA runtime-managed temporary root, such as /tmp/toolang-<agent>-<hash>/<root>/agents/<agent>/
RoamingA sibling .toolang/ directory next to the source, unless the command surface supplies a root<root>/agents/<agent>/

For roaming agents, a sibling toolang.toml can be linked into the materialized home as config.toml.

Visiting roots are disposable and independent of the local TOOLANG_ROOT.

Files

Most visible files, including .env, config.toml, agent.too, cap files, task files, and chore files, are authored and editable. Their formats are chosen to be human-readable whenever possible. You can edit them directly or manage them through Toolang commands.

Hidden directories such as .caps/, .runtime/, and .sandbox/ are managed by Toolang and plugins. They contain prepared artifacts, lock data, runtime state, logs, scheduler state, and run records.

FileScopesDescription
.envroot, homeLocal environment defaults.
config.tomlroot, homeTOML configuration, model defaults, plugin settings, and cap wiring.
agent.toohomeThe authored source for one agent.
{cap dirs}root, homeEditable cap directories: psyches/, skills/, services/, and prompts/.
{job dirs}homeEditable job directories: tasks/, chores/, and archive/.
.caps/root, homePrepared cap artifacts and lock data. Do not edit directly.
.runtime/homeRuntime status, logs, run records, scheduler state, plugin state, and local ids.
.sandbox/rootHost-side sandbox staging, such as generated launcher files.

Prepared state can usually be deleted and regenerated when repairing a local installation.

Be careful with .runtime/: agent run history is stored there, so deleting it may remove past runs, logs, local ids, scheduler state, and other runtime records.

© 2026 Toolang