EFEnvForgeJoin waitlist

Docs / Getting started

Get to the first EnvForge workspace in six steps.

The first-time flow is concrete: connect GitHub, prepare each repo with a reviewable envforge.yml PR, create the project services and bindings, install the CLI, run envforge login, then run envforge up.

  1. Connect GitHub
  2. Prepare envforge.yml PRs
  3. Create project
  4. Bind services
  5. Install CLI
  6. envforge login
  7. envforge up
Review repo-prep PRsReview workspace lifecycle
first workspacehappy path

GitHub App connected for acme/scheduler

PR opened: add envforge.yml

Project: Scheduler; services: Web, Backend

Bindings: web -> Web, /api -> Backend

$npm install -g envforge

$envforge login

$envforge up

First workspace preflight

Assign owners before the first workspace wakes.

A successful first run depends on more than the CLI command. Before envforge up, make sure repo setup, access policy, resource modes, and runtime cost posture have named owners.

Repo ownerenvforge.yml approval

A repo owner reviews the generated service command, port, inputs, dev routes, runtime default, and smoke check before the setup PR merges.

The workspace contract should be owned by the team that owns the code.
Access ownerAuth0 + roles

An organization admin confirms Auth0 login, EnvForge roles, GitHub App installation scope, and who can issue signed dev links.

Identity is not enough; product roles decide workspace actions.
Resource ownerresource modes

Each database, cache, bucket, mail sink, queue, or disabled integration has an owner, mode, readiness expectation, and cleanup policy.

Resource decisions should not be discovered during reviewer handoff.
Cost ownersize + sleep + cap

The first workspace names its runtime size, idle sleep behavior, cap posture, and separate customer-cloud costs before the runtime wakes.

Awake-only billing is useful only when the boundary is visible.

Hosted MVP milestone

The first hosted MVP is a workspace handoff, not a production-ready claim.

The milestone is the hosted path a first customer or reviewer can follow: run envforge up, land in a shell immediately, let runtime services wake in the background, share a signed dev.envforge.ai URL, and explain that runtime billing applies only while the runtime is awake.

hosted MVPnot GA
  1. envforge upCLI entry point

    Open the prepared hosted workspace.

    After GitHub, repo setup, project services, and CLI login are ready, envforge up selects the hosted project and branch workspace instead of asking users to rebuild local setup.

  2. instant hosted shellshell first

    Attach before service boot blocks work.

    The shell attaches first with Git, tmux, Claude, Codex, repo checkout, and logs ready while service processes report readiness separately.

  3. background runtimewake as needed

    Service capacity starts behind the shell.

    Web, /api, workers, resources, or checks wake in the background when runtime work needs CPU, memory, ports, or declared service dependencies.

  4. signed dev.envforge.ai URLreview link

    Share the app surface through the gateway.

    The reviewer opens a signed dev.envforge.ai URL for the service/workspace/org host, and the signed session gates web, /api, assets, and realtime traffic.

  5. runtime billing while awakemeter boundary

    Bill runtime use, not shell existence.

    Opening a signed dev URL can wake the runtime; idle sleep stops the runtime meter while the hosted shell, repo state, and workspace metadata remain available.

Current hosted MVPfirst milestone

The hosted path is the first milestone: envforge up, instant shell attach, background runtime wake, signed dev.envforge.ai handoff, and awake-only runtime billing.

Local scaffoldingcontract examples

Local envforge.yml examples and setup PRs describe the contract that the hosted workspace will run; they are not the hosted shell, gateway, runtime meter, or billing system by themselves.

Planned production hardeningdo not overclaim

Keep GA onboarding, expanded fleet controls, automated caps, invoices, and production operations language clearly planned until those controls are live; this is not a production-GA availability claim.

Workspace access contract

Start from the CLI, share the signed dev URL, and keep runtime billing separate.

Getting started should leave one clear handoff: envforge upopens the workspace shell, the dev URL follows the service/workspace/org shape, and a signed session gates app traffic before the runtime wakes.

envforge upworkspace handoff

$envforge up signed-links

shell: ready with Git, tmux, Claude, Codex

runtime: asleep until web, /api, workers, or checks need it

handoff: signed dev.envforge.ai URL -> browser session

dev: https://web--signed-links--acme.dev.envforge.ai

session: signed service/workspace/org, expires 2h

billing: shell baseline included; runtime meter awake-only

  • CLI front doorenvforge up

    The terminal chooses the workspace.

    Developers and agents enter through the CLI, select the organization, project, repo workspace, and branch, then attach to the shared shell without passing around raw VM hostnames.

    One command is the handoff handle for Git, tmux, Claude, Codex, logs, and readiness.
  • Dev URL shape<service>--<workspace>--<org>.dev.envforge.ai

    Dev hosts name the product surface.

    EnvForge calls this a signed dev.envforge.ai URL in product handoffs; the dev.envforge.ai host keeps the service, workspace, and organization visible for review while DNS stays behind one EnvForge wildcard.

    Use a signed dev link for the actual browser handoff, not a raw runtime address.
  • Signed dev linkservice + workspace + org + expiration

    The link creates a scoped browser session.

    Signed links cover the app surface for web, same-origin /api, assets, and realtime routes, while SSH, logs, secrets, private consoles, and runtime admin remain closed.

    The host shape is not the permission; the signed session is.
  • Billing splitshell included / runtime awake-only

    Shell access and runtime usage are separate.

    The shell baseline stays ready for repo work. Web, API, workers, tests, and resources wake the runtime meter only when service work needs them.

    Auto-sleep stops runtime billing without deleting the workspace.

Connect GitHub

Connect the GitHub organization and selected repos.

Install GitHub App

Start by installing the EnvForge GitHub App for the organization and choosing the repositories EnvForge is allowed to prepare.

Use selected repositories; setup does not require broad personal access tokens.

Prepare repos

Prepare each repo with a focused envforge.yml PR.

envforge.yml PR per repo

EnvForge reads each repo and opens a small setup PR with service commands, ports, inputs, resources, dev routes, runtime defaults, and smoke checks.

Repo owners review the contract before branch workspaces depend on it.

Create project

Create the project, services, and bindings.

Project -> services -> bindings

Add the prepared repos as project services, then bind product routes and resources: Web owns the browser surface, Backend owns /api, and declared resources attach to the services that consume them.

Bindings turn repo services into a product-shaped workspace.

Install CLI

Install the CLI where you run Git.

npm install -g envforge

The CLI is the normal workspace handoff for developers and agents. Install it in the terminal environment that should attach to EnvForge workspaces.

Verify the install with envforge --version before first login.

envforge login

Sign the CLI into the EnvForge organization.

envforge login

envforge login opens the product sign-in flow and returns a local CLI session tied to the same organization and GitHub installation.

The CLI should show the expected organization before opening a workspace.

envforge up

Open the first branch workspace.

envforge up

Run envforge up, choose the prepared project and branch, then land in the shell while web, API, resources, checks, and signed dev readiness start in the background.

Shell first; service runtime wakes only when workspace work needs it.

First workspace trust receipt

Before the first reviewer opens the link, verify the trust receipt.

The first workspace handoff should make access, isolation, and cost plain in product language before anyone opens the app dev URL.

Review full trust modelReview signed dev links
Dev URL model*.dev.envforge.ai

The dev URL follows the product host shape <service>--<workspace>--<org>.dev.envforge.ai through one EnvForge wildcard, not raw VM hosts or per-branch DNS.

Use the signed dev link for the browser handoff.
Signed dev sessionservice + workspace + org + expiration

Reviewer access starts as one signed browser session for one service, workspace, organization, and expiration before app traffic reaches the runtime.

Web, /api, assets, and realtime paths share the session.
Isolationone-org-per-VM

Shell and runtime VMs stay inside one customer organization, so cross-customer code, dev traffic, and logs never co-tenant.

Branch workspaces can share only their owning org boundary.
Runtime billingruntime-awake only

Opening the signed link may wake web, /api, workers, or checks on the runtime meter; idle sleep stops billing while the shell baseline remains ready.

Cost follows awake service work, not the existence of a workspace.

Resource readiness

Confirm resource readiness from the CLI before sharing handoffs.

After envforge up, run envforge workspace resourcesto check declared resources by reference, readiness, and consumer service. The handoff should explain what is ready, waking, or blocked without exposing credentials or provider internals.

workspace resourcessafe readiness

$envforge workspace resources signed-links

resource.postgres.url ready for api

resource.cache.url waking for api

resource.storage.bucket blocked for web: disabled by workspace policy

masked: postgres://***@resource.postgres/app

  1. Readyresource.postgres.url

    The value can be injected when the service wakes.

    Ready means the workspace mode resolved and the consuming service can receive the masked reference during runtime wake.

  2. Wakingresource.cache.url

    The runtime or backing service is still catching up.

    Waking is a reason to wait before handing a reviewer the link, then run the command again after provisioning or service wake completes.

  3. Blockedresource.storage.bucket

    A policy or setup decision needs an owner.

    Blocked output should name the resource and consumer service without printing credentials, provider IDs, internal hosts, or private console URLs.

Ready-to-share packet

Paste the signed link with scope, readiness, and billing state.

Once the first workspace is green, the useful artifact is a short packet a reviewer can trust. It should name the signed dev URL, what the browser session covers, what is ready, and whether opening the link may wake the metered runtime.

share packetPR comment

Workspace: signed-links / acme

Dev link: https://web--signed-links--acme.dev.envforge.ai

Session: signed web, /api, assets, realtime; expires 2h

Readiness: web ready; api ready; postgres ready; cache waking

Billing: dev URL may wake runtime; shell baseline included

Private: SSH, logs, secrets, root, resource consoles

  1. Link<service>--<workspace>--<org>

    Share the signed URL, not infrastructure.

    Use the generated dev.envforge.ai host through the signed link so reviewers open the app surface without raw hosts, ports, VM names, or cloud resource IDs.

  2. Scopeweb + /api + assets + realtime

    Name what the browser session covers.

    Call out the selected service and route families so reviewers know API calls, assets, and realtime traffic use the same signed workspace session.

  3. Readinessready / waking / blocked

    Attach current runtime and resource state.

    A green handoff should say which services, checks, and resources are ready, which are still waking, and what is blocked before the link is opened.

  4. Metershell included / runtime awake-only

    Explain what may start billing.

    Opening the signed link can wake web, API, workers, or checks on the runtime meter; the shell baseline stays included and idle sleep stops service billing.

First workspace handoff

Hand back a shell, a signed dev URL, and readiness state.

A launch-ready first workspace should be easy to paste into a pull request or support thread: the workspace shell, the signed dev URL, what is ready, and which operational surfaces remain private.

handoff receiptdev URL contract
Host shape<service>--<workspace>--<org>.dev.envforge.ai
  • Shellenvforge up signed-links

    Humans and agents land in the same branch shell.

    The handoff names the workspace, Git branch, tmux session, logs, and shell status before service runtime work starts blocking review.

  • Dev URLweb--signed-links--acme.dev.envforge.ai

    Reviewers get the signed app surface.

    The public host follows <service>--<workspace>--<org>.dev.envforge.ai, with one browser session for web, /api, assets, and realtime routes.

  • Readinessweb ready; api waking

    Runtime state travels with the link.

    The first workspace handoff should say which services, resources, and checks are ready, still waking, or blocked before a reviewer opens the app.

  • Boundaryssh / logs / secrets blocked

    Dev access does not become admin access.

    Signed dev URLs stay app-scoped. SSH, raw logs, secrets, root policy, private consoles, and runtime admin remain behind authenticated workspace access.

Setup contract

Keep repo setup and project binding separate.

The per-repo PR says how a service runs. The project binding says where that service belongs in the product workspace, such as routing web to Web and /api to Backend.

envforge.ymlper repo PR
version: 1
service:
  name: Backend
  command: npm run api
  port: 3000
  inputs:
    DATABASE_URL: resource.postgres.url
resources:
  postgres:
    mode: branch_scoped
preview:
  routes:
    - /api
checks:
  smoke: npm test

Project bindings

Routesweb + /api
ServicesWeb + Backend

First-run checks

The setup is ready when these are true.

A first workspace should be runnable from product concepts and reviewed repo contracts, without passing around raw VM hostnames, cloud credentials, or shared secrets.

  • GitHub App access is limited to the repositories EnvForge should prepare.
  • Each selected repo has one reviewable envforge.yml setup PR.
  • Project services are created from those prepared repos.
  • Bindings connect web, /api, and workspace resources to named services.
  • npm install -g envforge succeeds and envforge --version returns a CLI version.
  • envforge login shows the expected organization context.
  • envforge up opens the shell and reports service, resource, and signed dev readiness.