Workspaces

A Workspace is the core OpenAlice working asset: a repo-shaped place where an agent does a real task. It has files, instructions, tools, terminal output, git history, and artifacts the agent can leave behind.

It is the main container for Trading as Collaboration. OpenAlice turns trading work into issue-shaped, file-shaped, git-shaped collaboration so humans and agents can share context instead of passing around isolated recommendations.

What a workspace gives Alice

• A working repo. The agent can write Markdown, scripts, notes, issue files, and committed artifacts inside a normal git directory.
• A native agent CLI. The model loop runs inside claude, codex, opencode, pi, or shell, so OpenAlice does not need to reimplement each vendor's terminal UI, prompt cache, or session format. Pi can additionally render the same conversation through the beta WebPi browser surface.
• OpenAlice tools on PATH. The alice* CLIs expose market data, RSS, analysis tools, workspace collaboration, entity tracking, and optional beta trading commands.
• Durable context. A workspace can accumulate files, issues, tracked entities, inbox entries, and git history across many sessions.
• A delivery path. Finished reports and checkpoints can be pushed to the Inbox, linked back to the workspace that produced them.
• Durable coworkers. Every agent Session has a stable resumeId, so reports, Issues, and scheduled runs can point back to the exact conversation that produced them.

Workspaces are the recommended substrate for any non-trivial AI work. Interactive sessions and scheduled jobs both run through workspace-backed agent CLIs; scheduled jobs use workspace automation.

The core surfaces

OpenAlice's main product surfaces are built around workspace-shaped work:

The everyday chat workspace is the simplest example: OpenAlice packages the context and workbench for talking about markets into a git repo, injects the alice* CLI surface, and lets the agent work like it is handling a coding task.

New conversation versus new workspace

New conversation creates a fresh Session inside the selected or most recently active Chat Workspace. New Workspace creates a new durable context container with its own files, Issues, git history, and settings.

OpenAlice remembers the recent Chat Workspace and reuses it for Quick Chat. It does not create a date-based Workspace every day: a calendar boundary is not a context boundary, and daily repositories would strand yesterday's files and history.

For credential-backed Pi and opencode launches, Quick Chat shows the effective model and context window before sending. Existing Workspace configuration wins; choosing another provider is a visible new injection rather than a hidden global fallback.

Several Sessions can share one Workspace. Each receives its own stable resumeId; opening a finished headless run or an Inbox sender reuses that product Session instead of fabricating a new identity. See Sessions & Collaboration.

Coordinate and maintain the floor

The launcher-level Workspace Manager is a dedicated Pi/WebPi control plane, not a business Workspace. Use it to inventory active desks, ask exact Sessions, review Issue health, and preview template upgrades.

Durable Workspaces can also:

• reconcile newer launcher-managed assets through a three-way Template Upgrade;
• directionally absorb selected files from another Workspace and archive the source;
• switch complete data homes when the desktop needs separate environments.

See Upgrades & Absorb and Data & Credentials.

Leaving the active floor

Workspaces are offboarded, not blindly deleted. OpenAlice writes a handoff, moves the complete checkout to a departed inventory, and retires its Session signatures. Restore returns the exact path and identities; purge removes the checkout but keeps historical attribution. See Lifecycle & Offboarding.

Runtime defaults

Choosing an agent in Ask Alice saves it as the user-level default for future interactive Workspace sessions. The default is only used when that runtime is enabled for the target workspace; otherwise OpenAlice falls back to the workspace's first enabled agent runtime. shell remains a utility adapter and cannot become the stored default.

Scheduled issue runs have a separate default under Issue Settings → Default agent runtime. This lets interactive chat favor one runtime while unattended work uses another. Resolution order is:

1. the issue's explicit agent frontmatter;
2. the Issue Settings default;
3. the interactive Workspace default;
4. the workspace's first enabled agent runtime.

These runtime choices are separate from default Workspace credentials: one chooses the CLI, the other chooses which model credential/config is seeded for that CLI.

Where to go deeper

• Trading as Collaboration - the product model behind workspaces, issues, Inbox, entities, and git.
• Workspace Structure - directory layout, git repo, terminal session, lifecycle, and headless runs.
• Sessions & Collaboration - durable Session identities, signatures, exact follow-up, and WebPi.
• Lifecycle & Offboarding - handoff, departed desks, restore, purge, and Session retirement.
• Workspace Manager - coordinate active desks from one accountable control plane.
• Upgrades & Absorb - safely update or consolidate durable Workspaces.
• CLI Injection - how the alice* binaries expose OpenAlice to the agent without an MCP shim.
• Settings Injection - how persona, skills, and AI provider credentials are written into the workspace.
• Self-Describing Issues - how issue files double as work items, schedules, graph nodes, and run context.

Next Steps

• Quick Start - Use a workspace-backed conversation end to end.
• Issue Board - Track work and schedule recurring runs with the same Markdown file.
• Inbox - See how agents push finished work back to you.