Skip to content

Environments: up, sh, exec, down

An environment (a fork) is a running copy of your stack made from a snapshot. Everything in this guide happens inside one.

Terminal window
forkstage up

Forks the newest snapshot of the stack in the current folder. Ready in about 100 ms; the whole round trip is about a second. The block it prints is the fork’s identity card: id, address, services and ports, stop limits, and the next commands.

Forks are listed in the dashboard under Environments and by forkstage ls on your machine.

https://<id>.forkstage.run reaches the app service’s port. Other HTTP services are at https://<id>-<port>.forkstage.run. The database and other non-HTTP services are private to the fork; reach them with forkstage exec or forkstage sh.

The address works for anyone who has it while the fork runs, and stops answering when the fork is destroyed.

Terminal window
forkstage sh # the app service
forkstage sh --service db

An interactive shell inside a service’s container, over a WebSocket to the host. You get a real prompt, your window size follows, and exit returns to your terminal. Every shell session is recorded in the proof as one event.

Terminal window
forkstage exec -- npm test
forkstage exec --service db -- psql -U forkstage app -c "select count(*) from orders"

Runs one command inside a service and prints its output; the exit code is yours. Each command is recorded in the proof with its exit code, duration and the last lines of output. Use -- so the command’s own flags are not read by Forkstage.

Terminal window
forkstage test
forkstage test --only unit

Runs the recipe’s tests inside the fork and records each as a test run with counts. See Tests and proofs.

Terminal window
forkstage logs # every service, last 100 lines
forkstage logs -s app -n 500
forkstage status # the fork's card plus each service's state
Terminal window
forkstage up # again: a second fork of the same stack
forkstage ls # every fork this machine knows about
forkstage exec k8a8vx -- npm test # name the fork when there is more than one

Each fork is independent: its own database, its own address. The workspace limit (5 at once by default) is the only coupling.

Terminal window
forkstage down # the latest fork in this folder
forkstage down k8a8vx
forkstage down --all

Destroys the fork at once and keeps the proof. The output names the proof:

× struck k8a8vx after 2m 41s · proof: forkstage proof k8a8vx

Forks also end by themselves: after the workspace’s idle stop (30 minutes without a command or a request to the address, by default), at the hard stop (8 hours), or when the pull request that made them closes. Finished forks show why they ended in the dashboard.

“Idle” means no exec, test, sh or request through the public address. Opening the address in a browser counts; an agent that only talks to the address is not idle-stopped.