Setting up a new environment

You just got a new machine, or you're on a client that asked you to run their stack locally. This workspace orchestrates it all: Docker, variables, processes, and narration.

Nodes on the canvas

Node	Role
Env pointing at .env.local	Variables everything else consumes.
Docker	Brings up Postgres, Redis, S3 mock — anything in compose.
Process Manager with api, worker, frontend	Keeps the app services running.
Terminal	For one-off commands (migrations, seeds).
Agent Terminal	Coordinates, narrates, fixes.
Text (named "Setup status")	Live dashboard.

Connections

From → To	Kind	What it does
Env → Process Manager	port ports:variables->applyEnv	Variables become each process's env.
Env → Docker	manual	Compose reads env from .env.local.
Docker → Text	port ports:containerLogs->appendText	Container logs flow into the text.
Process Manager → Text	port ports:logs->appendText	App process logs flow in.
Process Manager → Text	port ports:runningCount->setContent	"3/3 running" counter at the top of the text.
Agent Terminal → Docker	permission docker-full-access	Agent brings containers up/down, reads logs, executes.
Agent Terminal → Process Manager	permission proc-control	Agent starts, stops, restarts processes.
Agent Terminal → Terminal	permission execute	Agent runs migrations, seeds.
Agent Terminal → Env	permission env-read	Agent checks variables (won't expose secrets).

Ideal setup sequence

Configure the Process Manager with three entries, autoStart: false:

• api — npm run dev:api
• worker — npm run dev:worker
• frontend — npm run dev:web

And the Docker node with docker-compose.yml auto-detected.

Prompt

Bring the local environment up. Plan:

1. Check .env.local via the Env node. If anything required by
   docker-compose.yml or the processes is missing, list it and stop.
   Don't invent values.

2. Run `docker compose up -d` via the Docker node. Wait for all
   services (postgres, redis) to become healthy. If anything fails,
   show me the failing container's logs and ask before trying to fix.

3. In the Terminal, run migrations: `npm run db:migrate`. If it
   errors, read the message and tell me your hypothesis.

4. Start the three processes in the Process Manager in this order:
   api, worker, frontend. Confirm all leave the "starting" state and
   reach "running", staying stable for at least 10 seconds.

5. Confirm the frontend is reachable by opening http://localhost:3000
   in a Webview node (create one if needed).

6. Update the "Setup status" text with the final state: what came up,
   what failed, next steps.

Why this setup is comfortable

• Env as source of truth: variables live in one place, propagate to processes and Docker via port.
• Process Manager shows process state in color — green, yellow, red. You don't have to memorize commands.
• Crashes go back to the agent: if a process dies, the ports:crashes->prompt port (not used here, but you can wire it) pings the agent, which tries to restart or diagnose.
• Logs into the text give a persistent dashboard — you close the workspace, open tomorrow, the text is there with history.

Variations

• Local CI: swap npm run dev:* for npm run ci:* and add a Task Node firing "run tests every 5 minutes".
• New client: save this workspace as templates/onboarding.riggr in the client's repo. The next dev clones, opens, and the agent walks them through setup.
• More paranoia: swap proc-control for proc-list + proc-status (read-only). The agent only observes; you push the buttons.