Docs
GitHubBlog

Search Documentation

Search for a page in the docs

Structure

A workspace is a task repo plus a long-lived agent runtime. The repo gives the agent a place to read, write, commit, and leave artifacts. The runtime gives the user a terminal they can attach to, leave running, or resume later.

Directory shape

Each workspace lives under ~/.openalice/workspaces/<wsId>/ and contains:

  • The agent's working directory, fully read/write/git commit-able from inside.
  • A git repo initialized at creation, so every file change is reviewable.
  • Instruction files for the chosen agent family, usually CLAUDE.md and AGENTS.md.
  • Template-specific files, scripts, data folders, or cloned project contents.
  • Optional issue files under .alice/issues/<id>.md.
~/.openalice/workspaces/
├── <wsId>/
│   ├── .git/
│   ├── CLAUDE.md
│   ├── AGENTS.md
│   ├── .alice/
│   │   └── issues/
│   └── ...
└── auto-quant-mirror/

The wsId is opaque and stable. It is what the /cli/<wsId> gateway carries, what Inbox entries key on, and what headless runs attach to. The human-readable workspace tag is separate and editable.

Terminal session

The persistent terminal session is hosted by OpenAlice and surfaced in the Web UI. You can read it, type into it, scroll back, or leave it running while the agent works.

The model loop itself runs in the native CLI selected for that workspace: claude, codex, opencode, pi, or shell. OpenAlice does not translate every model event into a universal protocol. It gives the CLI a workspace, injects the right context, and lets the CLI run.

Lifecycle

  1. Create - Pick a template, agent, and tag. The bootstrap script materializes the directory, writes instructions, injects settings, and initializes git.
  2. Run - Open the workspace. The persistent terminal attaches to the workspace directory with the chosen CLI started.
  3. Iterate - The agent reads, writes, runs commands, commits, and pushes reports to the Inbox.
  4. Pause - Closing the workspace tab leaves the session running in the background. Re-opening reattaches.
  5. Delete - Removes the workspace directory. Inbox entries pointing at it become tombstones because the source repo is gone.

Headless runs

The same structure powers scheduled and async work. A scheduled issue or explicit headless request launches an agent non-interactively against the same workspace repo. The run captures the agent session id and full output log, then appears in the Runs tab and under its workspace in the sidebar.

A finished headless run can be opened as an interactive session, so you continue from the exact repo, files, and agent output the headless run left behind.

Next Steps