Workspaces
From the project documentation.
A workspace definition is a directory with a corb.toml
file outside every mount. Its directory name identifies the workspace. A
session combines that definition with global settings and any CLI
overrides.
Use corb run --workspace <name> to select a
definition. You can also run corb run DIR. Corb selects a
workspace whose own host paths contain DIR. If no workspace matches,
Corb uses global settings and adds DIR as a mount.
There is no creation or registration command. Corb does not read repository-local policy files or run setup scripts. Follow the development walkthrough for a complete example.
Each run starts a fresh VM and one Pi process. Multiple mounts belong to that same session and agent. Mounted host files persist. Guest-only files and default Pi history do not. The walkthrough shows how to mount persistent history.
Directory mounts
corb run ~/Code/packet-loss \
--dir reference=/home/bec/Code/reference:ro \
--dir scratch=/home/bec/Code/scratch:rw \
--trust-config| Directory | Guest path | Access |
|---|---|---|
| packet-loss | /work/packet-loss |
Read/write |
| reference | /work/reference |
Read only |
| scratch | /work/scratch |
Read/write |
The mounts expose the host directories directly. Corb does not copy their contents or create separate checkouts or Git worktrees. Sessions that mount the same host path share its files, and ordinary read/write edits are visible to the host and other sessions using that directory.
Replace the example paths with existing directories on your host.
Without --workspace, an omitted DIR defaults to your
current directory. If DIR is outside the selected workspace's own hosts,
Corb adds it as a read/write mount. Each additional directory gets a
guest path based on its name.
Pi starts in the matching workspace mount, or the added positional
mount. --primary scratch changes its working directory to
/work/scratch. All configured mounts remain available.
To make the positional directory read only, override its generated mount by name:
corb run ~/Code/packet-loss \
--dir "packet-loss=$HOME/Code/packet-loss:ro"This example assumes you have already accepted the persistent
configuration. Add --trust-config when required.
Configuration resolution
built-in defaults
+ global config.toml
+ selected workspace corb.toml
+ positional directory, only when outside the workspace's own hosts
+ CLI overrides
= effective session configuration
Every global [[dir]] participates in every run. Global
egress.allow values also remain in workspace runs. A
workspace can set every option except [workspaces]. That
table stays in the personal global file.
Security lists only add. A workspace cannot remove a global directory entry or an earlier rule. Scalars replace. This covers VM settings, provider, model, policy, and Git push permission.
Directories merge by name. Later host,
mode, create, and protect-git
fields replace earlier values. Rules for the same directory append
across layers. Secret hosts replace instead of appending.
The trust check flags every widening change.
A workspace that sets a brokered [agent] provider gets
its API hosts added to egress.allow.
corb explain marks them as implied and names the workspace.
If a change implies a new host, the next run needs
--trust-config.
Without a workspace match, the positional directory retains its
existing behavior. Its generated rw mode overrides a global
ro entry with the same name. Use a CLI override when you
need a read-only positional mount.
Selection and primary directory
--workspace <name> selects the winning copy from
the ordered sources below. An unknown or invalid name is an error.
Without that flag, Corb loads every valid winning workspace. A broken
file is an error even when another workspace matches DIR.
Only hosts set in a workspace's own file count for path selection. Host-less entries and hosts inherited from global entries do not count. Corb compares paths after resolving symlinks. More than one matching workspace is an error that names the candidates. If several hosts within one workspace contain DIR, the deepest host wins.
When DIR equals or is inside a workspace host, Corb adds no extra
mount. That host's mount becomes primary. Pi starts at its root, such as
/work/project, even for a subdirectory DIR. Otherwise Corb
adds DIR after the workspace layer. If its basename conflicts with a
hosted mount name, Corb reports an error and suggests
--dir NAME=HOST. A same-named entry without a host is
allowed.
With --workspace <name> and no DIR, Corb does not
mount cwd automatically. Global configured mounts still apply. The first
hosted entry in the workspace's own file becomes primary. If the file
has no hosted entry, you must give --primary for a hosted
global or CLI entry. Use --primary NAME to choose another
mount.
Portable host paths
Corb expands a complete leading ~ or $HOME
component in every [[dir]] host. Relative hosts use the
global projects-root:
[workspaces]
projects-root = "~/Code"A workspace file can then use host = "packet-loss" for
~/Code/packet-loss. Without projects-root, a
relative host is an error. This also applies to global
config.toml. projects-root must be absolute
after home expansion and cannot appear in a workspace file. Empty hosts
and forms such as ~bob/x, ${HOME}/x, and
$OTHER/x are errors.
--dir NAME=HOST also expands ~ and
$HOME. Relative CLI hosts still use cwd. Corb expands hosts
before selection, the mount guard, and trust hashing. This does not
expand ~ in audit.path or other path
settings.
Rules within a directory
[[dir]]
name = "packet-loss"
rules = [
{ glob = "**/.env*", mode = "hidden" },
{ glob = "**/*_test.go", mode = "deny-write" },
]When you run the packet-loss directory, the generated
mount supplies its host path and the rules above remain attached. Globs
are relative to that mount's root.
This host-less entry must match the basename of an added positional
directory. It does not apply when DIR is inside a workspace host. Put
rules and protect-git on that workspace entry instead.
Other host-less entries need a host path before a real run.
hidden makes a path absent from listings and access.
deny-read blocks reads and writes. deny-write
preserves reads while refusing edits.
These restrictions apply through the host filesystem provider to shell commands and other guest processes, as well as Pi's own file tools.
Even without a repository at startup, every read/write mount gets
built-in Git protection. These deny-write rules run before
user rules. They protect the root .git entry, config files
and locks, hooks, and commondir. They also cover metadata
under .git/modules/** and .git/worktrees/*.
Read-only mounts already block writes and need no built-in rules.
Set protect-git = false in a [[dir]] entry
to disable this protection for that mount. For the positional directory,
use a host-less entry with its basename, as in the example above. See
the rule list and
side effects and the security limits. Nested
repositories and a submodule's own .git file remain outside
this protection.
Trust and inspection
corb explain ~/Code/packet-loss
corb run ~/Code/packet-loss --dry-run
corb workspace ls
corb workspace show packet-loss
corb explain --workspace packet-loss --trustedCorb keeps personal acceptance records in
~/.config/corb/trusted.json. Runs without a workspace use
the positional directory's resolved absolute path as the key. Workspace
runs use workspace:<name>:<resolved dir>.
When DIR is inside a workspace host, that host's resolved path
supplies <resolved dir>. All subdirectories of that
host share one record. With no DIR, Corb uses the default primary host,
or the explicit primary when the workspace has no own host. When Corb
adds DIR as an extra mount, the key uses that resolved DIR instead.
Corb does not reuse old path-keyed records for workspace runs. The
first workspace run therefore needs --trust-config
once.
A first run, or a change that widens policy, requires
--trust-config. Examples include a new permitted host, a
mount change from ro to rw, Git push
permission, and removal of a filesystem rule. Narrowing changes apply
without confirmation.
Disabling Git protection requires confirmation. Mode changes between
rw and ro also require confirmation for
protected mounts. Adding protection to an older trust record needs no
new acceptance. corb explain lists built-in rules
separately from user rules, and its JSON output includes
builtin-rules on each directory.
CLI overrides are treated as explicit user choices. They affect the running session but are excluded from the stored trust snapshot.
After git pull updates shared definitions, use
corb workspace ls to find changed settings. Review one
workspace with corb workspace show <name>. Use
corb explain --workspace <name> DIR --trusted to
review a specific extra mount. Both print the full accepted snapshot
alongside current settings and the trust comparison. Accept a widening
change with
corb run --workspace <name> --trust-config.
narrowed means the current config removes access and can
run without confirmation. Removing an allowed host narrows access.
Changing rw to ro also narrows an unprotected
mount. Protected mode changes still require confirmation, as described
above. The old snapshot stays until a run uses
--trust-config again. An order-only difference is shown
separately and does not affect trust.
Implied hosts are marked in current config only. Accepted snapshots include the allowed hosts but no source metadata, so the snapshot carries a note instead. Secret names and host metadata are visible. Secret values are never printed.
workspace ls lists records for missing workspace names
after its table. These orphan records stay in the personal trust store.
Listing never deletes them. An extra-mount record for a deleted
directory shows cannot compare in show. A
workspace without own hosted mounts still shows its details and
extra-mount records. Run that workspace with
--workspace <name> DIR.
Workspace sources
A workspace definition is a directory at
<source>/<name>/, with one
corb.toml file. The directory name identifies the
workspace. A name inside its TOML remains a session label.
The file uses the global configuration schema except
[workspaces], which stays personal. Optional layer pins
live in the winning workspace directory's corb.sum. The layer contract
defines its strict version-1 format.
The global config.toml lists source directories in
order:
[workspaces]
paths = ["~/corbfiles/workspaces", "~/.config/corb/workspaces"]When paths is unset, the default is
<configDir>/workspaces. It follows
CORB_CONFIG_DIR. An explicit list replaces that default.
Use paths = [] to disable all sources. Source paths also
expand a leading ~ or $HOME.
Later sources replace earlier workspaces with the same name. They
replace the whole directory instead of merging its files.
corb explain shows source order and missing paths. It marks
invalid names and replaced copies. corb doctor reports
source counts and problems. A missing source is allowed, but a dangling
source symlink is an error.
A team can share a "corbfiles" Git checkout and add its workspace
directory as a source. Each user keeps trusted.json in
their personal config directory. Never commit trusted.json
to a source. Corb refuses trust records in a source or its child
directories.
Corb refuses mounts that overlap any source or workspace directory.
This covers replaced and invalid copies. The guard resolves symlinks and
protects linked corb.toml and existing
corb.sum targets too. Even a missing source stays protected
when a mount contains its future location.
CORB_CONFIG_DIR remains supported. It selects the
personal configuration directory, its trusted.json, and the
default workspace source. Workspace files still layer above that
selected global config.toml.
Layer inspection and local state
A workspace can own one [image.layer] definition. Global
[image] tables are errors. Sources replace that complete
definition with the rest of the workspace directory.
[vm].image remains the local base selector.
Recipes declare Alpine package names, ordered root install commands,
SDK archives, runtime hosts and runtime directories. Build and archive
download hosts grant no runtime access. Runtime hosts follow provider
hosts in implied-host processing. Current output labels them
[image.layer] hosts in workspace "<name>". Accepted
snapshots show the same shareable settings without current source
labels.
corb explain, corb run --dry-run and
corb workspace show can inspect a recipe without pins or a
built generation. Missing pins show
corb image pin --workspace <name>. Malformed pins
fail inspection. The lock comes from the winning workspace. Corb
validates symlink targets and ignores locks from cwd or replaced
sources. Without a layer, Corb omits image and does not
parse corb.sum.
Review definition and selected pin changes before accepting them. Every addition, edit or removal requires trust confirmation. Changes from pins alone also require confirmation. Another architecture's valid pins do not affect the selected trust record. Existing workspace and directory trust keys keep their format.
Share the definition and authenticated input identities through version control. Base choices, composed generations, output hashes, account numbers and checkpoints remain local. Runtime directories name required paths and system accounts. They do not launch services or run startup scripts. The security guide describes package compatibility and archive limits.
Explicit pin, build and layer transport commands use this same
winning workspace. --workspace NAME works without any
hosted directory or primary mount. Without it, cwd selection retains
source and ambiguity errors. No cwd mount is invented.
These commands never accept personal normal-run trust. Normal run validates the current exact-base generation before reading credentials or starting a VM. See layer sharing for producer and recipient steps, local state and recovery limits.