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 --mode single_agent --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 state — message history, memory, open files — is checkpointed. Hot-restart and the agent picks up where it left off.

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. Currently this returns a clear “not yet available” message in v0.1 and is the post-launch fast-follow.