Workspaces

What is a workspace?

A workspace is a saved configuration that tells jackin’ how to mount your project directories into an agent container. Instead of typing long mount paths every time, you save a project boundary once and reference it by name.

A workspace is not the same thing as an agent class:

workspace = which project files are available
agent class = which tools, plugins, and defaults are installed

That means one workspace can be reused with multiple agent classes when the file access should stay the same but the runtime profile should differ.

In practice, that is one of the main reasons workspaces exist. They let you preserve the same file boundary while swapping in the agent class that best matches the work.

The current directory workspace

The simplest way to use jackin’ is from your project directory:

cd ~/Projects/my-app
jackin load agent-smith

This creates a current-directory workspace that mounts the current directory (~/Projects/my-app) into the container at the same absolute path. The agent sees the exact same directory layout you do.

Why save a workspace?

Loading the current directory is perfect when you are already standing in the project and only need a simple one-directory mount.

Saved workspaces become useful when you want that setup to be reusable and predictable.

They let you:

name a project boundary once and launch it from anywhere
keep extra mounts consistent across sessions
reuse the same project boundary with different specialized agent classes
let jackin launch auto-detect and preselect the project
set a default agent or restrict which agent classes may use the workspace

If you regularly work on the same project, a saved workspace turns your mount layout into durable operator configuration instead of something you rebuild from memory each time.

Saving workspaces

For projects you work on regularly, save a workspace:

jackin workspace add my-app --workdir ~/Projects/my-app

Now you can load agents into it from anywhere:

jackin load agent-smith my-app

Or load a different agent class into the same workspace:

jackin load the-architect my-app

This is the key pattern to keep in mind: the workspace stays the same because the project boundary stays the same, but the agent class changes because the job changes. You might use chainargos/frontend-engineer for UI work in the morning and chainargos/backend-engineer for API work in the afternoon, both against the same saved workspace.

What `--workdir` does

The --workdir path serves two purposes:

Working directory — the container’s cwd when the agent starts
Auto-mount — by default, the workdir is automatically mounted at the same path inside the container

Adding extra mounts

Workspaces can include additional directories beyond the workdir:

jackin workspace add my-app \
  --workdir ~/Projects/my-app \
  --mount ~/cache:/cache:ro \
  --mount ~/shared-libs:/libs:ro

Controlling the mount layout

If you need the container layout to differ from your host:

jackin workspace add monorepo \
  --workdir /workspace \
  --no-workdir-mount \
  --mount ~/src:/workspace

Here, --no-workdir-mount disables the automatic workdir mount, and you provide all mounts explicitly.

Managing workspaces

List all workspaces

jackin workspace list

Show workspace details

jackin workspace show my-app

Edit a workspace

# Change the workdir
jackin workspace edit my-app --workdir ~/Projects/my-app-v2

# Add a mount
jackin workspace edit my-app --mount ~/data:/data:ro

# Remove a mount by its container destination
jackin workspace edit my-app --remove-destination /old-mount

Delete a workspace

jackin workspace remove my-app

Restricting agents

You can limit which agents are allowed to use a workspace:

jackin workspace add secure-api \
  --workdir ~/Projects/secure-api \
  --allowed-agent agent-smith \
  --default-agent agent-smith

--allowed-agent — only these agents can load this workspace (repeatable)
--default-agent — auto-selected agent class when you use jackin launch with this workspace

This is especially useful when one workspace should only be used with a very specific tool profile, such as a production-infra agent or a security-review agent.

Editing agent restrictions

# Grant access to another agent
jackin workspace edit secure-api --allowed-agent the-architect

# Revoke access
jackin workspace edit secure-api --remove-allowed-agent the-architect

# Change default agent
jackin workspace edit secure-api --default-agent neo

# Clear the default agent
jackin workspace edit secure-api --clear-default-agent

Workspace auto-detection

When you run jackin launch, the TUI launcher checks if your current directory exactly matches a saved workspace’s workdir. If it does, that workspace is preselected — saving you a selection step and reinforcing the value of naming project boundaries once. This auto-detection works best when the saved workspace keeps the host path and container workdir the same. If you remap workdir to a container-only path like /workspace, choose that saved workspace manually in the launcher. You can always override the preselection by choosing a different workspace or “Current directory.”

Storage

Workspace definitions are stored in ~/.config/jackin/config.toml. They’re local operator configuration — not part of any project or agent repo.