jackin❯ workspace

Synopsis

jackin workspace <SUBCOMMAND>

Create, list, modify, and delete saved workspace definitions.

A workspace describes project access, not agent tooling. It answers: which host paths should be mounted into the container, and which roles are allowed to use that layout?

Subcommands

workspace create

jackin workspace create <NAME> --workdir <PATH> --mount <SPEC> [OPTIONS]

Create a new workspace definition.

jackin workspace create my-app --workdir ~/Projects/my-app --mount ~/Projects/my-app
jackin workspace create my-app --workdir ~/Projects/my-app --mount ~/Projects/my-app --mount ~/cache:/cache:ro
jackin workspace create amp-app --workdir ~/Projects/amp-app --mount ~/Projects/amp-app --default-agent amp
jackin workspace create monorepo --workdir /workspace --mount ~/src:/workspace
jackin workspace create restricted --workdir ~/app --mount ~/app --allowed-role agent-smith --default-role agent-smith
jackin workspace create remote --workdir ~/Projects/remote --mount ~/Projects/remote --keep-awake

# Isolated source mount + shared cache child
jackin workspace create jackin \
  --workdir /workspace/jackin \
  --mount ~/projects/jackin:/workspace/jackin \
  --mount ~/.cache/jackin/target:/workspace/jackin/target \
  --mount-isolation /workspace/jackin=worktree

workspace list

jackin workspace list [--format <human|json>]

Show all saved workspaces. Pass --format json for machine-readable output with a schema_version field.

workspace show

jackin workspace show <NAME> [--format <human|json>]

Display details of a specific workspace including workdir, mounts, and role restrictions. Pass --format json for structured output.

The mount table includes an Isolation column showing each mount's effective isolation mode (shared, worktree, or clone). Mounts with no isolation field in TOML display as shared.

workspace edit

jackin workspace edit <NAME> [OPTIONS]

Modify an existing workspace.

jackin workspace edit my-app --workdir ~/new-dir
jackin workspace edit my-app --mount ~/cache:/cache:ro
jackin workspace edit my-app --remove-destination /old-mount
jackin workspace edit my-app --allowed-role chainargos/backend-engineer
jackin workspace edit my-app --default-role agent-smith
jackin workspace edit my-app --clear-default-role
jackin workspace edit my-app --default-agent amp
jackin workspace edit my-app --clear-default-agent
jackin workspace edit my-app --keep-awake
jackin workspace edit my-app --no-keep-awake
jackin workspace edit my-app --git-pull
jackin workspace edit my-app --no-git-pull

# Flip an existing mount to per-container worktrees
jackin workspace edit my-app --mount-isolation /workspace/my-app=worktree

# Change the host src of a previously materialized isolated mount
# (non-interactive; explicitly accept that preserved state will be deleted)
jackin workspace edit my-app \
  --mount ~/projects/my-app-v2:/workspace/my-app \
  --delete-isolated-state

workspace edit rejects isolation changes on a running container with a clear "eject first" message. Source-drift edits that would invalidate preserved isolated state prompt interactively; non-interactive runs require --delete-isolated-state to proceed.

Mount collapse

When you add a mount that is an ancestor of existing mounts (same host-to-container offset), the descendants become redundant. jackin workspace edit detects this and prompts before removing them:

Adding mount(s) will subsume 2 existing mount(s):
  • ~/Projects/proj-alpha/sub-a
  • ~/Projects/proj-alpha/sub-b
These will be removed from the workspace.
Proceed? [y/N]

Flags:

• --yes / -y — skip the prompt (required for non-interactive use).
• --prune — also clean up pre-existing redundant mounts in the workspace.

Conflict cases that are rejected with an error (not prompted):

• Readonly mismatch. Parent and descendant have different :ro flags.
• Child under existing parent. Adding a mount that is already covered by a pre-existing mount in the workspace.

In both cases the error text names both paths and the operator's next step.

workspace remove

jackin workspace remove <NAME>

Delete a saved workspace.

workspace prune

jackin workspace prune <NAME> [OPTIONS]

Remove pre-existing redundant mounts from a saved workspace. Useful when upgrading from an older jackin❯ config or after a hand-edit that left redundants.

jackin workspace prune my-app        # interactive
jackin workspace prune my-app --yes  # non-interactive

A mount is redundant when another mount in the same workspace strictly covers it at the same container location — same host-to-container offset. See Redundant mounts in the mounts guide.

workspace env

Manage operator env vars at workspace and workspace-role scope.

Values are stored verbatim — op://... 1Password references, $VAR / ${VAR} shell-style interpolations, and literal strings all work. jackin❯ resolves values at launch time; there is no editor-side validation of key names or value shape.

Without --role, writes and reads target the workspace-wide scope (applies to every role launch in this workspace). With --role <SELECTOR>, they target the per-(workspace × role) scope (applies only when that role is launched in this workspace). The workspace must already exist — unknown workspaces fail fast with a non-zero exit. The role selector is not pre-validated.

workspace env set

jackin workspace env set <WORKSPACE> <KEY> <VALUE> [OPTIONS]

Set or overwrite an env var at the chosen scope.

# Workspace scope
jackin workspace env set prod DB_URL "op://Work/Prod/db-url"

# Workspace-role scope
jackin workspace env set prod OPENAI_KEY "op://Work/OpenAI/key" --role agent-smith

# Attach a comment
jackin workspace env set prod DEBUG "1" --comment "temporary; remove after Q2"

# On-demand credential: never resolved at launch, approved per use
jackin workspace env set prod OP_TOKEN "op://Work/svc-account/credential" --on-demand

workspace env unset

jackin workspace env unset <WORKSPACE> <KEY> [OPTIONS]

Remove an env var from the chosen scope. Idempotent: if the key is not present, prints <KEY> not set. and exits 0 without modifying anything. Fails fast if <WORKSPACE> does not exist.

jackin workspace env unset prod DB_URL
jackin workspace env unset prod OPENAI_KEY --role agent-smith

workspace env list

jackin workspace env list <WORKSPACE> [OPTIONS]

Show the env vars registered at the chosen scope as a table with Key, Value, and On demand columns. Prints No env vars set. when the scope is empty. Values are shown as-stored (no resolution, no masking); On demand is yes for a value resolved at jackin-exec time rather than injected at launch. Fails fast if <WORKSPACE> does not exist.

jackin workspace env list prod
jackin workspace env list prod --role agent-smith

workspace account

Authorize named accounts for a workspace and choose which account each coding agent uses.

jackin workspace account list my-app
jackin workspace account assign my-app work
jackin workspace account select my-app work --agent claude
jackin workspace account select my-app work --agent claude --role agent-smith
jackin workspace account select my-app --agent claude --clear
jackin workspace account unassign my-app work

Assignment grants access. Selection chooses among granted accounts. A global account or global selection never expands a workspace's allowlist. With no compatible account, no agent credentials are forwarded; multiple compatible accounts require an explicit selection.

Create and remove registry entries with account commands. Account changes take effect on the next launch; they do not revoke tokens at the provider.