org / project / repo / branchThe durable handoff names the organization, project, repository, branch, workspace slug, and current owner without exposing raw VM hostnames, IP addresses, or cloud resource IDs.
Docs / Workspace policies
Workspace policies keep metadata and runtime decisions reviewable.
A branch workspace should expose the metadata teams need to resume work without exposing VM internals. Runtime policy says what size can wake, when it sleeps, how caps behave, and which state remains available while the service runtime is asleep.
workspace policymetadata first
workspace: signed-links
metadata: acme / scheduler / web / feature/signed-links
runtime: Small; sleep: idle; cap: warn before stop
retained asleep: shell, repo, metadata, signed-link state
wakes: dev links, tests, services, workers
private: root policy, secrets, logs, runtime admin
Metadata boundary
Workspace metadata is the durable handoff, not the runtime host.
Metadata is what the CLI, dashboard, and agents use to reattach to the same branch workspace. It should explain state and policy while keeping provider implementation details out of product handoffs.
shell / runtime / resourcesShell attach state, runtime wake state, resource bindings, check results, and blockers stay visible so humans and agents can resume the same workspace without reconstructing local setup.
size / sleep / capRuntime size, idle-sleep behavior, usage cap posture, cleanup intent, and signed-link state travel with the workspace while service CPU can still sleep.
Runtime policy flow
Policy is read before service work wakes.
Runtime policy sits between the workspace identity and the metered services. It gives operators a visible contract for what can wake, how much capacity it gets, when it sleeps, and which events remain part of the workspace record.
runtime policywake contract
- Select
envforge up signed-linksThe CLI opens a named workspace.
The user or agent chooses an organization, project, repo, and branch. EnvForge returns the workspace metadata first so the shell can open before service runtime work blocks progress.
- Apply
Small + sleep: idle + capRuntime policy is read before wake.
The workspace policy sets the runtime size, idle-sleep rule, and usage cap posture before dev links, tests, workers, or service commands start paid runtime capacity.
- Record
ready / waking / blockedReadiness changes become metadata.
Runtime wake, resource readiness, smoke checks, cap warnings, and sleep events are recorded as workspace state instead of being hidden inside a host session.
- Govern
root and secrets stay separateRuntime policy does not widen privilege.
Root access, secret values, logs, private consoles, and runtime admin stay behind access policy. Changing size or sleep settings does not change those boundaries.
Review checklist
A workspace policy is ready when the handoff explains these boundaries.
Keep this review at the product layer: workspace identity, runtime defaults, retained state, and access boundaries. Cloud wiring and secret values should stay out of policy copy.
no raw hostsReview notes should name the workspace, branch, service readiness, and next owner without sharing VM names, IP addresses, provider resource IDs, or private ports.
People resume the product workspace, not the machine.size + sleep + capBefore a workspace wakes, the policy should state the selected runtime size, idle-sleep rule, usage cap behavior, and what work can wake services.
Cost behavior is visible before dev links or agents run.asleep is not deletedIdle sleep should preserve shell access, repo storage, metadata, declared artifacts, readiness history, and signed-link state until cleanup is explicit.
Teams can stop runtime spend without losing context.policy is not privilegeRuntime size, caps, and sleep rules do not grant root, expose secrets, open logs, or turn private admin surfaces into signed dev links.
Operational access remains governed separately.