envforge up connects to the shell immediately. The shell owns Git, tmux, Claude, Codex, editor tools, repo checkouts, light tests, and the workspace context a developer can inspect.
Docs / runtime model
Shell opens first; runtime wakes only for service work.
EnvForge separates the workspace entry point from the app stack. The shell gives developers and agents immediate access to code and tools. The runtime wakes behind it for web, API, resources, tests, and signed dev sessions, then sleeps when service work goes idle.
workspace entryruntime background wake
clienvforge up signed-links
shellready immediately
runtimewaking services + resources
sleepstops runtime meter
Boundary
Runtime is a compute layer, not the whole product.
Product decisions stay in the control plane. Host work happens in the daemon. The runtime layer is the awake app capacity users pay for only while services need it.
The runtime owns web, api, workers, database, Redis, MinIO, Mailpit, service processes, health checks, logs, and signed dev link traffic while service work needs capacity.
Laravel keeps product state: organizations, projects, workspaces, permissions, schedules, command records, usage sessions, and billing boundaries.
The Go daemon is the hands on the VM. It registers the host, sends heartbeats, polls commands, writes env files, starts services, checks health, and reports results.
Lifecycle
The runtime should trail the shell, not block it.
The expected first-release loop is attach first, wake service work in the background, then sleep the runtime without deleting the workspace.
- Attachenvforge up signed-links
The CLI resolves the workspace and opens the shell without making the developer wait for web, API, or resources to boot.
- PreparePREPARE_SHELL
The shell daemon makes the workspace directory, Linux user, checkouts, README, and .envforge context ready on shared workspace storage.
- WakeSTART_RUNTIME
The runtime daemon provisions local resource namespaces, renders service env files, starts service processes, and reports readiness.
- Sleepenvforge sleep
Sleeping the runtime stops service capacity billing while preserving the shell, workspace files, database data, storage data, logs within retention, and access policy.
Decision rule
Put work in the layer that owns the failure mode.
This keeps implementation honest: Laravel can retry product commands, the daemon can recover host actions, and users see shell, runtime, service, and billing states separately.
- Does this action need service processes, databases, workers, signed dev traffic, or integration tests? If yes, it belongs to the runtime layer.
- Does this action need code, Git, tmux, Claude, Codex, repo setup, static checks, or a human shell? If yes, it belongs to the shell layer.
- Does this action decide who can do something, where a workspace belongs, or what should be billed? If yes, it belongs to the control plane.
- Does this action require touching the VM filesystem, processes, ports, users, cgroups, resource daemons, or host health? If yes, it belongs to the Go host daemon.