Sessions

A Session is an agent (or a lattice of agents) running inside a single directory. The session sandbox is a container (podman) bind-mounted to your directory. The agent reads, writes, and runs commands inside. You see every action stream into the dashboard.

Starting a session

From the dashboard:

1. Open Sessions.
2. Click + Add folder in the sidebar to authorize a directory.
3. Pick the folder, choose Single agent, pick an agent (coder works for most coding tasks), click Use this folder.

A new session boots in a fresh container with your folder bind-mounted. The cockpit opens with Files / Activity / Lattice / Browser panes plus a Terminals pane at the bottom.

From the CLI:

axocoatl session new ./my-repo --agent coder

What the agent can do

Once running, the agent has tools to operate inside the sandbox:

• read_file / write_file / edit_file / list_dir / glob / grep
• bash — run a one-shot command and capture stdout/stderr.
• bash_background — run a long-lived process in the background (e.g., python3 serve.py). Lives until you kill it or the session ends.
• spawn_terminal — open a PTY-backed terminal in the dashboard’s Terminals pane. You see the output live.
• read_terminal / kill_terminal — let the agent inspect or stop terminals it spawned.

Every tool call shows up in the Activity pane as a chip with collapsible output.

State survives

Close the laptop. Open it tomorrow. The session is still there. The container is gone (it’ll respawn), but the agent’s conversation transcript is checkpointed to disk. Hot-restart and the agent picks up the conversation where it left off. (The checkpoint restores the transcript only — not token-usage accounting or in-flight tool state; the agent rebuilds the rest. Its longer-term knowledge lives in the memory tiers, which are persisted independently of the checkpoint.)

The seeded demo

On daemon boot, a demo session called demo-counters is auto-created in {data_dir}/demos/counters (if it doesn’t already exist). It’s a tiny folder you can experiment in safely. From the Sessions tab, click the demo-counters row to enter it. Ask the agent to make some counter files in Python; watch the bash terminal run them.

Lattice mode

SessionMode::Lattice runs multiple agents together inside one directory. The full lattice cascades work between them — exactly like a multi-agent workflow, but bounded to a folder: the session runs the workflow’s agents in dependency order, scoped and sandboxed to that folder. session new on the CLI creates single-agent sessions today, so lattice-mode sessions are created through the API or dashboard.