Layout and Storage

This page defines the filesystem layout used by Toolang and the canonical identity model for agents.

Core terms

toolang root the local Toolang system directory, defaulting to ~/.toolang
agent home the local directory that hosts one or more .too files
agent room the private machine-managed area for one agent
resident agent an agent whose home lives under ${TOOLANG_ROOT}/agents/
roaming agent an agent whose home stays at an external local path
visiting agent an agent discovered from a remote URL and materialized under ${TOOLANG_ROOT}/guests/

Canonical agent URIs

Canonical URI forms:

agent://<home_name>/<agent_name>.too resident agent
file:///absolute/path/to/<agent_name>.too roaming agent
https://<host>/<path> visiting agent

Rules:

agent_id = hash(agent_uri)
canonical identity stays separate from local placement
agent_uri must not depend on the absolute TOOLANG_ROOT path

Toolang root

{TOOLANG_ROOT}/
  agents.db
  agents.too
  sync/
    skills/
    services/
    prompts/
    psyches/
  skills/
  services/
  prompts/
  psyches/
  agents/{HOME}/
  guests/{HOME}/
  sandbox/{AGENT_KEY}/
  bus/
    events.db
    bus.run
    bus.log

This is where Toolang keeps the global registry, global shared source, global local capabilities, synced output, resident or visiting agent homes, and the shared bus projection.

Agent home

${AGENT_HOME}/
  {AGENT}.too
  agents.too
  channels.toml
  hooks.toml
  .env
  .toolang/
    agents/{AGENT}/
    sync/
      {AGENT}.state.json
      skills/
      services/
      prompts/
      psyches/
    skills/
    services/
    prompts/
    psyches/

The agent home is the split between authored state and machine-managed state:

authored source stays in .too, .env, and loop config files
shared local capabilities stay under .toolang/{skills,services,prompts,psyches}/
generated synced output stays under .toolang/sync/

Agent room

${AGENT_HOME}/.toolang/agents/{AGENT}/
  agent.run
  agent.log
  execution.db
  pulse.json
  task_mirrors.json
  runs/
    {RUN_ID}/
      prompt.json
  poll/
  hooks/
  sync/
    skills/
    services/
    prompts/
    psyches/
  chats/
    chats.db
  sandbox/
  tasks/
    *.md
  chores/
    *.md
  will.md

The agent room is the local truth layer for one agent. It holds runtime state, task files, chat history, traces, and loop-owned state.

Scope roots

Capability scopes map to these roots:

agent
- source: ${AGENT_HOME}/{AGENT}.too
- sync: ${AGENT_HOME}/.toolang/agents/{AGENT}/sync/
shared
- source: ${AGENT_HOME}/agents.too
- local: ${AGENT_HOME}/.toolang/{skills,services,prompts,psyches}/
- sync: ${AGENT_HOME}/.toolang/sync/
global
- source: ${TOOLANG_ROOT}/agents.too
- local: ${TOOLANG_ROOT}/{skills,services,prompts,psyches}/
- sync: ${TOOLANG_ROOT}/sync/