onyx-dev-stack
Skill320 starsChanged 8 days agoMITView on GitHub
Start, inspect, restart, or stop an Onyx development stack with ODS. Prefer frontend-only previews for frontend-only diffs, shared infrastructure for ordinary work, and explicit isolation for independent datasets. Do not use for Kubernetes development.
- Reads credentials
1 other project uses a version of this, 1 of them edited.
Adopted by
Most recently taken up by
- onyx-dot-app/onyxedited, first seen Oct 17, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 1
- onyx-dot-app/onyx★ 33k88% same
Wrote their own version · 0
None found.
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository10 other files it gives its agents.
- AGENTS.mdAGENTS.md
- backend/AGENTS.mdAGENTS.md
- documentation/AGENTS.mdAGENTS.md
- mobile/AGENTS.mdAGENTS.md
- web/AGENTS.mdAGENTS.md
- docs-writingSkill
- feature-mapSkill
- merge-dependabot-prsSkill
- onyx-craft-devSkill
- playwright-e2e-testsSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
26 rules. About 0 are common, 9 are distinctive, and 17 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
Distinctive · estimate
This author's own choices. Worth a look.
17
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 8
Run from the worktree that contains the code being tested.
- Very specific: line 12
Check for uv, bun, and a running Docker daemon.
- Very specific: line 18
Check ods web dev --help and ods --help too.
- Very specific: line 27
Use the selected command for the remaining steps.
- Very specific: line 39
If a matching frontend already runs in this checkout, ODS attaches instead.
- Very specific: line 58
Use the reported web URL for browser tests and HTTP requests.
- Distinctive: line 62
If the database is already at head, unchanged healthy services keep running.
- Distinctive: line 64
Run a slow startup in a background terminal when available.
- Very specific: line 66
Read "$ODS" stack up --help before choosing a different profile:
- Very specific: line 72
Use --local-model-server only when changing model-server code.
- Very specific: line 79
Use ods --isolated stack up for separate state, ports, Compose projects, databases, queues, indexes, and object storage.
- Very specific: line 80
Use ods web dev for frontend-only diffs with a healthy managed API.
- Very specific: line 89
Stop managed services before manual db upgrade or db downgrade.
- Distinctive: line 91
Do not stop another worktree's services or kill unrelated processes to free a port.
- Very specific: line 92
Keep .vscode/.env and .vscode/.env.web untracked.
- Distinctive: line 94
Use shared mode for sequential development and frontend previews.
- Very specific: line 105
If the stack starts on unexpected ports, or Docker resources run low, run "$ODS" stack ls --all to see the other stacks on the machine.
- Very specific: line 107
Run "$ODS" stack logs --help to select a service or follow logs.
- Very specific: line 114
Use disposable worktrees with ods --isolated stack up for these tests.
- Distinctive: line 116
Never reset a developer database to satisfy a test fixture.
- Distinctive: line 121
Stop managed application processes while keeping infrastructure available:
- Distinctive: line 127
Stop the worktree's application processes and infrastructure:
- Distinctive: line 135
After shutdown, inspect status to confirm the targeted stack stopped.
- Very specific: line 139
Run "$ODS" stack ls from any directory.
- Very specific: line 141
Stop orphaned stacks; no worktree owns them.
- Very specific: line 142
Do not add --force, prune --yes, or prune --volumes unless the user asks.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Onyx dev stack
Run from the worktree that contains the code being tested. ODS owns processes, ports, state, and logs.
Select ODS
Check for uv, bun, and a running Docker daemon. Use the repository-pinned ODS when it provides the stack command:
uv run --frozen --only-group ods ods stack --helpCheck ods web dev --help and ods --help too. If the pinned package lacks the shared-stack behavior, build ODS from this checkout. This requires Go:
ODS_BUILD_DIR="$(mktemp -d "$(git rev-parse --path-format=absolute --git-path ods-stack-bin).XXXXXX")"
ODS="$ODS_BUILD_DIR/ods"
go -C tools/ods build -o "$ODS" .
"$ODS" stack --helpUse the selected command for the remaining steps. Examples below use "$ODS"; replace that prefix with the pinned invocation when available.
Start and discover
For frontend-only diffs on macOS or Linux, run the frontend against an existing healthy managed API:
"$ODS" web devThis foreground command starts only the web server. Keep its terminal running.
It requires a healthy managed API. Ctrl-C stops a newly launched preview.
If a matching frontend already runs in this checkout, ODS attaches instead;
Ctrl-C then only detaches. stack status does not list standalone previews.
Ctrl-C also cancels dependency installation and library builds during startup.
It does not run migrations, start workers, or start containers. If no healthy API
exists, start the default stack first. Use a full stack for backend changes and
OAuth callback testing, because the reused API retains its original web origin.
Other ods web scripts, including build and test, remain package-script commands.
On Windows, web dev and backend use portable foreground launchers and
configured connection variables. Managed stacks, API discovery, and attachment
are macOS/Linux behavior. Check the frontend URL directly after a Windows launch.
For ordinary work, start the default profile with shared infrastructure:
"$ODS" stack up --timeout 12m
"$ODS" stack status --jsonUse the reported web URL for browser tests and HTTP requests. Do not assume port 3000 or call a backend port directly.
up prepares local environment files and dependencies, reuses shared infrastructure, applies migrations, and reconciles background application services. Existing secrets stay private. Ask for a model key only when the requested test needs one.
Pending migrations stop managed application services before changing the schema.
If the database is already at head, unchanged healthy services keep running.
Run a slow startup in a background terminal when available. Wait for its exit and inspect status before reporting success.
Read "$ODS" stack up --help before choosing a different profile:
minimalruns web and API for UI/API work.defaultadds the workers needed for ordinary indexing and background tasks.fullruns the full launch compound for integration work.
Use --local-model-server only when changing model-server code. Other profiles use Compose inference and avoid a duplicate local model process.
Repeat the profile and local-model flag with start or restart. Use up to change model mode or recover infrastructure.
Multiple agents
- Agents in the same worktree share one stack. Reuse a healthy stack through
upandstatus. - By default, worktrees share infrastructure and one active application checkout. Running
upelsewhere stops the prior managed app before migrations. - Use
ods --isolated stack upfor separate state, ports, Compose projects, databases, queues, indexes, and object storage. Repeat--isolatedfor later commands. - Use
ods web devfor frontend-only diffs with a healthy managed API. Its Ctrl-C behavior leaves the reused API running. - Shared status reports the active checkout. Run stop, down, start, and restart there. Only up transfers ownership.
- Legacy datasets are preserved. If several exist at first shared startup, select the intended one with
--project; never choose by timestamps. Stop its legacy stack with--isolatedbefore adoption. - Legacy discovery reads saved
ods stackstate. Compose-only setups need their previous--project NAMEexplicitly. Useods --project NAME stack upto save that shared selection before using the default commands. - Project ownership is durable. An explicit project collision fails, including in isolated mode. Select a different project for independent infrastructure.
- ODS keeps a stack's ports while it runs.
stopreleases the application ports (web, API, MCP, model, metrics) and keeps the infrastructure ports.downreleases all of them. Another stack can reclaim the ports of a stopped stack, and a stopped stack moves back to the lowest free port. Read status again after a restart or start. - The selected stack lock coordinates lifecycle changes. Shared handoffs serialize; isolated stacks can start independently.
- Foreground services and full stacks use the same service specifications and process launchers. A full stack replaces a same-checkout preview and retains its port.
- Database operations target exact project containers and use state/project locks. Do not work around a target conflict or another checkout's ownership guard.
- Stop managed services before manual
db upgradeordb downgrade. Usestack upfor pending-aware upgrades. - An explicit loopback database port resolves to its actual managed owner.
ods envleaves dotenv files unchanged if the selected Postgres container has no published port. - Do not stop another worktree's services or kill unrelated processes to free a port.
- Keep
.vscode/.envand.vscode/.env.webuntracked. Do not print their contents.
Use shared mode for sequential development and frontend previews. Use isolated mode for simultaneous backend branches, incompatible schemas, destructive tests, or independent datasets.
Inspect and recover
"$ODS" stack status --json
"$ODS" stack logsInspect the reported phase, failed services, and logs when startup is incomplete. Re-run up to recover a partial start. Preserve healthy services and report optional integrations that remain unavailable.
If the stack starts on unexpected ports, or Docker resources run low, run "$ODS" stack ls --all to see the other stacks on the machine.
Run "$ODS" stack logs --help to select a service or follow logs. Follow logs in a background terminal when continued observation is needed.
Successful startup requires the readiness check through the reported frontend URL. A process that exists is insufficient evidence.
Validate changes
For lifecycle, concurrency, browser, or real worker validation, read the ODS integration guide.
Use disposable worktrees with ods --isolated stack up for these tests. They create accounts, change the default test LLM provider, and stop services.
The browser smoke configuration supports an unlicensed local deployment. Its chat checks use a scripted local LLM, not a paid model key.
Never reset a developer database to satisfy a test fixture.
Database restore errors fail the command; SQL restores stop on SQL errors.
Stop
Stop managed application processes while keeping infrastructure available:
"$ODS" stack stopStop the worktree's application processes and infrastructure:
"$ODS" stack downNormal shutdown preserves volumes. Delete database, index, or object-store data only when the user explicitly requests a reset.
After shutdown, inspect status to confirm the targeted stack stopped. Check that another running worktree remains available when testing isolation.
Find and stop old stacks
Run "$ODS" stack ls from any directory. It lists every stack on the machine and prints the command that stops each one. Add --all for stopped stacks, --json for the same rows with a next field. Run "$ODS" stack ls --help for the statuses.
Stop orphaned stacks; no worktree owns them. Run the printed command, or confirm with the user before you stop a stack that another agent may still use.
Do not add --force, prune --yes, or prune --volumes unless the user asks.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

