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.
forkstage upForks 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.
The address
Section titled “The address”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.
forkstage sh # the app serviceforkstage sh --service dbAn 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.
forkstage exec -- npm testforkstage 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.
forkstage testforkstage test --only unitRuns the recipe’s tests inside the fork and records each as a test run with counts. See Tests and proofs.
logs and status
Section titled “logs and status”forkstage logs # every service, last 100 linesforkstage logs -s app -n 500forkstage status # the fork's card plus each service's stateSeveral forks
Section titled “Several forks”forkstage up # again: a second fork of the same stackforkstage ls # every fork this machine knows aboutforkstage exec k8a8vx -- npm test # name the fork when there is more than oneEach fork is independent: its own database, its own address. The workspace limit (5 at once by default) is the only coupling.
forkstage down # the latest fork in this folderforkstage down k8a8vxforkstage down --allDestroys the fork at once and keeps the proof. The output names the proof:
× struck k8a8vx after 2m 41s · proof: forkstage proof k8a8vxForks 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.
Activity
Section titled “Activity”“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.