Skip to content

Your first fork

This walk uses a small sample project, so you see the whole loop before touching your own code. It is a Spring Boot service for lending library books, with Postgres, migrations and seed data. You do not need Java installed.

Terminal window
git clone https://github.com/Metricall-AI-Lab/library-api.git
cd library-api

It already has a forkstage.yaml. Open it; this is the whole description Forkstage needs:

stack: library-api
services:
app:
build: .
port: 8080
env:
DATABASE_URL: postgres://forkstage:forkstage@db:5432/app
depends_on:
- db
db:
image: postgres:16
port: 5432
env:
POSTGRES_USER: forkstage
POSTGRES_PASSWORD: forkstage
POSTGRES_DB: app
data: empty
ready:
- http: app/health
tests:
- name: smoke
run: sh tests/smoke.sh

Two services, a line that says how Forkstage knows the app is up, and one test command. For your own project forkstage init writes this file; see Your own project.

Terminal window
forkstage bake
· Packing /Users/you/library-api
· Baking library-api/aae11de in workspace yourname (10 KB of source)
· Snapshot ready in 49.8 s on lat1
✓ Snapshot library-api/aae11de is ready (baked in 48.8 s)
Fork it: forkstage up

What happened: the repository went to a host, which built the image with Maven, started Postgres and the app, applied the two Flyway migrations (schema and four seed books), waited for /health, and froze the running VM. In the dashboard, Stacks now lists library-api with one snapshot named after the git commit.

Stacks: the library-api stack with its repository and newest snapshot.

Terminal window
forkstage up
· Forking library-api in workspace yourname
· Ready in 1.0 s end to end (fork 102 ms · host call 155 ms · control plane 182 ms · network 861 ms)
⌜▪⌝ forkstage library-api · snapshot aae11de · lat1
● f2ksm8 ready in 102 ms
address https://zk2r5a.forkstage.run
services app :8080 db :5432
stops idle 30 min · hard 8 h
next forkstage test f2ksm8
forkstage sh f2ksm8
forkstage exec f2ksm8 -- <command>
forkstage down f2ksm8
  • f2ksm8 is the fork’s id; the commands below take it, or leave it out and Forkstage picks the latest one in this folder.
  • The address is your copy on the internet while it runs. Open it with /books added: four seeded books.
  • stops: left alone, the fork stops after 30 minutes without commands or requests, and at 8 hours regardless.

In the dashboard, Environments shows it live, with an amber dot.

Environments: live forks with their addresses, and finished ones below.

Everything here happens inside the fork. Nothing touches anything real.

Run the project’s tests inside it:

Terminal window
forkstage test
· smoke: sh tests/smoke.sh in app
✓ passed 6 passed 1.7 s

Open a shell inside the app container:

Terminal window
forkstage sh

You land at root@…:/app#. Try curl localhost:8080/books, then exit.

Run a single command without a shell:

Terminal window
forkstage exec -- sh tests/smoke.sh

Look inside the database:

Terminal window
forkstage exec --service db -- psql -U forkstage app -c "select title, lent_to from books"

See the services’ logs:

Terminal window
forkstage logs
Terminal window
forkstage down
× struck f2ksm8 after 3m 13s · proof: forkstage proof f2ksm8

The fork is gone. What stays is the proof: open Proofs in the dashboard and click it.

A proof: the headline, the facts, the test runs and the timeline of every command.

That is the loop: bake once, then fork, use, strike, as often as you want. Forks take about 100 ms; you will stop thinking of them as precious.

The sample has one bug left in on purpose: lending a book that is already out succeeds and silently overwrites who has it. Good first task for an agent; see Agents.